Error codes

Every HTTP status HiWay returns and what it means.

Status	When	What to do
200	Request routed and answered successfully.	Read the response body. Check `X-HiWay-Routed-Model` to see what was picked.
400	Malformed request body, no provider key configured for the required tier, missing BYOK setup, or Security Shield in `block` mode detected a threat.	Fix the body, add the missing provider key, or review the Security Shield event log (`error.code: threat_blocked`).
401	Missing, invalid, or revoked API key.	Generate a new key in Dashboard → Keys and update your client.
402	Budget Control cap reached, monthly request quota exceeded, or passthrough grace cap exceeded (72h / 100k tokens after wallet hits 0).	Raise your Budget Control cap, upgrade your plan, wait for month reset, or top up your wallet. Read `error.code` to know which case.
403	Security Shield IP rule denies the client IP, or workspace suspended.	Add an `allow` rule for the IP under Dashboard → Security → IP Rules, or contact support if the workspace is suspended.
429	Per-key rate limit exceeded, OR Guardian blocked an anomaly.	Wait the `Retry-After` seconds. The error body contains `rule` and `retry_after_seconds`.
500	Internal HiWay error. Rare. The traceback is in our persistent logs.	Retry once. If it persists, ping [email protected] with the `X-Request-Id`.
502	All fallback candidates failed. Upstream providers are unavailable.	Check provider status pages. Look at `_hiway.fallback_chain` to see what was attempted.

Error response envelope

Every error returns a JSON body with this shape:

json

{
  "error": {
    "code":              "quota_exceeded",
    "message":           "Monthly request quota reached (500,000 / 500,000).",
    "included_requests": 500000,
    "used_requests":     500000,
    "upgrade_url":       "https://www.hiway2llm.com/upgrade"
  }
}

402 vs 429 vs 403

402 = money or quota (budget cap, plan quota, grace cap exceeded after wallet hits 0). 429 = rate or anomaly (RPM exceeded, Guardian block). 403 = identity or perimeter (IP rule deny, suspended workspace). Different retry semantics for each.