Skip to main content
When a request fails, the gateway returns a non-2xx HTTP status and a JSON body with a single error object. The shape is stable across every endpoint, so you can write one handler that covers all cases.

Error object

Every error response has this shape:
string
A human-readable description of what went wrong. Safe to log, but do not branch on the exact text: match on type and code instead.
string
The category of error. One of invalid_request_error, authentication_error, insufficient_credits, not_found, rate_limit_error, or upstream_error. This is the primary field to switch on.
string | null
A stable, machine-readable code when one is available, otherwise null. Examples: invalid_api_key, model_not_found, rate_limited, upstream_unavailable.
string
The id of the failed request. Include it when you contact support so the request can be traced. This matches the X-Request-Id response header.
The gateway never leaks upstream provider details. For provider or infrastructure failures, message is generic and the underlying detail is kept in the server-side logs keyed by request_id.

Request id header

Every response, success or error, carries an X-Request-Id header with a unique id for that request. On error responses the same value also appears as error.request_id.
Log X-Request-Id for every call, not just failures. It is the fastest way for support to locate a specific request.

Status codes

Each HTTP status maps to a single error type.

400 invalid_request_error

The request body did not validate. The message points at the offending field, and code is usually null.
Fix the request before retrying. Retrying an identical body will fail the same way.

401 authentication_error

The Authorization header is missing, or the key is not valid. The code is invalid_api_key.
Confirm you are sending Authorization: Bearer sk-... and that the key is active in the dashboard.

402 insufficient_credits

Your account has no remaining balance for platform models. The code is null.
Add funds on the pricing and billing pages, or configure a bring-your-own-key (BYOK) provider key to bill the provider directly.

404 not_found

The requested model or resource does not exist. The code is model_not_found for an unknown model id.
Call GET /v1/models for the live list of ids. See Models.

429 rate_limit_error

You have sent too many requests. The code is rate_limited.
A 429 response includes rate-limit headers. Wait for the Retry-After interval before retrying.
integer
Seconds to wait before retrying.
integer
Your request limit for the current window.
integer
Requests remaining in the current window.
integer
When the current window resets.

503 upstream_error

The model is temporarily unavailable, typically a transient provider or infrastructure failure. The code is upstream_unavailable, and the message is intentionally generic.
Retry after a short delay with exponential backoff.

Handling errors

Retry 429 and 503, which are transient. Do not retry 400, 401, 402, or 404 without changing the request, the key, the balance, or the model.
Do not retry 400, 401, 402, or 404 responses unchanged. They will keep failing until you fix the request, key, balance, or model id.

Next steps

Chat completions

The request and response fields for the main endpoint.

Models

List live model ids with GET /v1/models.

Authentication

Send your API key as a Bearer token.

Rate limits

Understand the 429 headers and backoff.