Errors

WRouter responses follow a unified error envelope:

json

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

HTTP status codes mirror OpenAI.

HTTP status

Status	Meaning	Typical cause
400	Bad request	Missing/invalid params, unsupported field
401	Unauthenticated	Missing/bad/disabled token
403	Forbidden	IP not allowed; token lacks model permission
404	Not found	Wrong model ID, missing file ID
409	Conflict	Duplicate resource
413	Payload too large	File/prompt/batch over limit
422	Unprocessable	JSON Schema validation failed
429	Too many requests	RPM exceeded, quota exhausted, balance low
499	Client closed request
500	Internal error	WRouter-side fault; safe to retry
502 / 503 / 504	Upstream failure	Upstream model unavailable/timeout — retry or fall back

`code`	Meaning
`invalid_api_key`	Token invalid
`expired_api_key`	Token expired
`disabled_api_key`	Token disabled
`ip_not_allowed`	IP not in allowlist
`model_not_found`	Unknown model ID
`model_not_authorized`	Token/group cannot use this model
`insufficient_quota`	Token quota exhausted
`insufficient_balance`	Account balance too low
`rate_limit_exceeded`	Rate limit hit
`content_policy_violation`	Policy block
`context_length_exceeded`	Input exceeds context window
`upstream_error`	Upstream returned an error (see `message`)
`upstream_timeout`	Upstream timed out
`internal_error`	WRouter internal fault

Error	Retry?	Notes
429	yes	Exponential back-off, starting at 1 s, capped at 60 s
500 / 502 / 503 / 504	yes	Same
`upstream_timeout`	yes	Lower `max_tokens` or switch model
Other 4xx	no	Fix the request

Both the OpenAI and Anthropic SDKs include retry logic out of the box.

Console → Call logs → click a row:

Submit the trace ID to support to accelerate triage.