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-Model` to see what was picked.
400	Malformed request body — missing model, invalid JSON, bad parameters.	Validate the body against the chat-completions schema.
401	Missing, invalid, or revoked API key.	Generate a new key in Settings → API Keys and update your client.
402	Insufficient credits, or per-key budget cap reached.	Top up at Dashboard → Billing, or raise your key's budget cap in Settings.
402	Worst-case cost of this single request exceeds your balance (strict spend rejection).	Top up enough credits, or lower `max_tokens` so the worst-case is smaller.
429	Per-key rate limit exceeded, OR Guardian blocked an anomaly, OR Budget Controls daily cap hit.	Wait the `Retry-After` seconds. The error body contains the `rule` and the `reason`.
500	Internal HiWay error. Rare. The full traceback is in our persistent logs.	Retry once. If it persists, ping support@hiway2llm.com with the `X-Request-Id`.
502	LLM provider unavailable or returned an error.	Switch to a different provider in your Settings → Providers or wait for the upstream provider to recover.

Error response shape

Every error returns a JSON body with this shape:

json

{
  "error": {
    "message": "Insufficient credits for this request (estimated max $0.0040, balance $0.0010). Top up at /billing",
    "type": "billing_error",
    "estimated_cost": 0.004046,
    "balance": 0.001
  }
}

402 vs 429

402 means money (no credits or budget exhausted). 429 means rate or anomaly (too many requests, Guardian, etc.). Don't confuse them.