Error codes
Current public error codes emitted by the gateway and the paths that use a null code.
This reference describes codes currently emitted by the public OpenAI-compatible /v1/* surface. It is deliberately not labelled exhaustive: new endpoints or contract-tested features can add codes. See Errors for envelope and retry guidance.
Codes emitted in error.code
| Code | HTTP | When |
|---|---|---|
payload_too_large | 413 | Chat or embeddings body exceeds its byte limit |
invalid_body | 400 | JSON parsing or request-schema validation fails |
model_not_found | 404 | The requested model slug is unknown or disabled |
model_does_not_support_images | 400 | A chat request contains an image for a non-vision model |
multimodal_not_supported | 400 | A chat content part has an unsupported type |
tool_choice_not_supported | 400 | Forced tool selection is requested |
response_format_not_supported | 400 | response_format or an SDK structured-output helper is used |
concurrency_limit | 429 | The per-key in-flight request limit is reached |
idempotency_conflict | 422 | One Idempotency-Key is reused for a different body |
upstream_unavailable | 502 / 503 | No route is available, the breaker is open, or transport fails before a response |
upstream_bad_request | 400 | Upstream returns 400 |
upstream_unauthorized | 401 / 403 | Upstream returns 401 or 403 |
upstream_model_unavailable | 404 | Upstream returns 404 for the configured model |
upstream_timeout | 408 / 504 | Upstream returns a timeout status |
upstream_rate_limited | 429 | Upstream returns 429 |
upstream_invalid_response | 502 | A non-streaming upstream response fails parsing or validation |
upstream_error | 5xx | Another upstream or response-building failure occurs |
internal_error | 500 | The global error handler catches an unexpected exception |
endpoint_not_supported | 404 | An unimplemented /v1/* endpoint is requested |
authentication_required | 401 | The authenticated quota endpoint has no resolved user |
Paths where error.code is null
The envelope permits code: null, and several current paths use it:
- Missing or invalid gateway credentials: HTTP 401,
type: "authentication_error". - Per-key request throttling: HTTP 429,
type: "rate_limit_exceeded". - AI credit balance exhaustion: HTTP 429,
type: "insufficient_quota".
In particular, AI credit exhaustion does not currently emit a distinct code; branch on HTTP 429 plus type: "insufficient_quota" while accepting a null code.
Streaming exception
Once a streaming HTTP 200 response has opened, a mid-stream failure cannot return this JSON envelope. The gateway sends a chunk with finish_reason: "error", then [DONE], and records internal status 502. A client disconnect is recorded internally as 499 and sends no response to the disconnected client.
The public API does not promise a Trace-Id response header. Supply the timestamp, endpoint, model slug, status, and returned envelope when asking an operator to investigate.