/v1/chat/completions, /v1/models, etc.) use the OpenAI error envelope. Anthropic-compatible endpoints (/v1/messages, /v1/messages/count_tokens) use the Anthropic error envelope.
Error envelope
OpenAI error envelope
Every non-2xx response on OpenAI-compatible endpoints uses this shape:
Notes:
- The envelope is flat under
error. There is nodetails[]array and no nested error objects. Content-Typeisapplication/json; charset=utf-8on every error response.- The response body is never empty; even 401 and 404 carry the envelope.
Anthropic error envelope
Anthropic-compatible endpoints (/v1/messages and /v1/messages/count_tokens) return errors in the Anthropic Messages API format:
The Anthropic envelope doesn’t carry
code, param, or doc_url. Routing, capability, and model-not-found errors include an optional suggestion with an actionable fix hint. Branch on error.type and HTTP status instead.
Required headers
Every response — success and error — carries:x-request-id— unique per request. Copy this when opening a support ticket. SDKs expose it asrequest_id(Python) /requestId(TypeScript) on every raised exception.
Retry-After— integer seconds. Present on 429 and 503. SDKs read this for automatic backoff.
Error types (OpenAI envelope)
The OpenAI envelope’stype field uses a closed set of six values:
Error codes
These codes are the canonical set, grouped by category. A published code’s meaning never changes. See the error-code reference for each code’s status and description.Authentication and authorization
Request validation
Routing — capability
Routing — constraint
Routing — policy
Routing — modality
Resources
Rate limits and quotas
Routing and providers
Server
Arbytra abstracts over multiple upstream LLM providers. Error messages name the model and the upstream provider that produced the error. The provider name appears in
error.provider and may appear in error.message. Failover across providers happens before a 429 or 5xx surfaces to the client.Retry policy
Branch ontype and code, not on HTTP status alone. The SDK retry loop uses the same rules.
Anthropic-compatible endpoints don’t carry
code. The Anthropic SDK retries based on HTTP status.Mid-stream errors (SSE)
Streaming endpoints returnContent-Type: text/event-stream. When the HTTP status is already committed as 200 OK and an error occurs mid-stream, the envelope surfaces as a final data: event and the stream closes:
- Errors never emit as partial JSON or a different SSE event name.
data: [DONE]signals successful completion only. After an error event, no[DONE]follows.- The connection closes immediately after the error event.
SDK exception dispatch
The Python and TypeScript SDKs dispatch incoming envelopes to typed exceptions. Every instance exposesmessage, type, code, param, request_id, doc_url, status_code, retry_after_seconds, and provider.
Built-in retry
The SDK retries onAPIConnectionError, rate_limit_error (except budget_exhausted and insufficient_quota), and api_error (except code: internal_error). Retries use exponential backoff and honor Retry-After when present.
Support
When reporting a failure to support, include thex-request-id from the response header (or request_id / requestId on the SDK exception). That single identifier pairs the client view with the server log.