Skip to main content
Arbytra returns errors in the format matching the endpoint’s API family. OpenAI-compatible endpoints (/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 no details[] array and no nested error objects.
  • Content-Type is application/json; charset=utf-8 on 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 as request_id (Python) / requestId (TypeScript) on every raised exception.
Error responses also carry, when applicable:
  • Retry-After — integer seconds. Present on 429 and 503. SDKs read this for automatic backoff.

Error types (OpenAI envelope)

The OpenAI envelope’s type 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 on type 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 return Content-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:
Rules:
  • 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 exposes message, type, code, param, request_id, doc_url, status_code, retry_after_seconds, and provider.

Built-in retry

The SDK retries on APIConnectionError, 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 the x-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.