Errors

The standard error envelope, current gateway codes, and safe retry guidance.

Learn

Error responses use the standard error envelope, so clients can inspect the HTTP status, error.type, and nullable error.code. The gateway does not forward raw upstream bodies. The tables below document current public /v1/* behavior, but they are not a promise that no additional code can be added.

Envelope shape

{
  "error": {
    "message": "Upstream rate-limited",
    "type": "api_error",
    "code": "upstream_rate_limited"
  }
}

Fields:

message — a client-safe summary.
type — a coarse category such as invalid_request_error, authentication_error, insufficient_quota, or api_error.
code — a more specific identifier when the emitting path supplies one; it can be null.

Common client and gateway codes

Code	HTTP	Meaning	Action
`payload_too_large`	413	Request body exceeded the route limit	Reduce the payload
`invalid_body`	400	Request JSON or schema is invalid	Fix the client payload
`model_not_found`	404	The model slug is unknown or disabled	Confirm the slug and catalog state
`model_does_not_support_images`	400	An `image_url` was sent to a non-vision model	Choose a vision-capable model or remove the image
`multimodal_not_supported`	400	A content-part type other than supported text/image input was sent	Remove the unsupported content part
`tool_choice_not_supported`	400	Forced tool selection was requested	Use automatic tool selection or omit `tool_choice`
`response_format_not_supported`	400	`response_format` / structured output was requested	Remove `response_format`; `generateObject` is not supported
`concurrency_limit`	429	Too many requests for the key are in flight	Retry after the supplied short delay
`idempotency_conflict`	422	An `Idempotency-Key` was reused with a different body	Use a new key or resend the original body
`endpoint_not_supported`	404	The requested `/v1/*` endpoint is not implemented	Use a documented endpoint
`internal_error`	500	The gateway raised an unexpected exception	Report the time, endpoint, and client-visible details to the operator

Authentication failures currently return HTTP 401 with type: "authentication_error" and code: null. Per-key request throttling returns HTTP 429 with type: "rate_limit_exceeded" and code: null. AI credit balance exhaustion returns HTTP 429 with type: "insufficient_quota" and code: null; there is no emitted distinct code in the current implementation.

Upstream codes

Code	HTTP	Meaning	Action
`upstream_unavailable`	502 / 503	No usable route, breaker-open state, or pre-response transport failure	Retry with backoff; honor `Retry-After` when present
`upstream_bad_request`	400	Upstream rejected the request	Correct or reduce the request
`upstream_unauthorized`	401 / 403	Gateway upstream credentials were rejected	Operator action required
`upstream_model_unavailable`	404	The configured upstream model id is unavailable	Operator action required
`upstream_timeout`	408 / 504	Upstream returned a timeout status	Retry with backoff
`upstream_rate_limited`	429	Upstream throttled the gateway	Retry with exponential jitter
`upstream_invalid_response`	502	A non-streaming upstream response failed parsing or validation	Retry; report persistent failures
`upstream_error`	5xx	Upstream returned another error or an unexpected non-streaming response	Retry; report persistent failures

A failure after an SSE response has started cannot become a JSON error response. See Streaming: the client receives finish_reason: "error" and [DONE], while the gateway records internal status 502.

Retrying safely

Retry transient upstream codes such as upstream_unavailable, upstream_rate_limited, upstream_timeout, and upstream_error, using capped exponential backoff with jitter. Do not automatically retry invalid payloads, unsupported features, unknown models, idempotency conflicts, or exhausted AI credit balance: those require a changed request, route, or account state.

The public OpenAI-compatible response does not promise a Trace-Id response header. When reporting a problem, provide the timestamp, endpoint, model slug, HTTP status, and returned error envelope; operators can correlate server-side request and trace records.