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 anX-Request-Id header with a unique id for that request. On error responses the same value also appears as error.request_id.
Status codes
Each HTTP status maps to a single errortype.
400 invalid_request_error
The request body did not validate. Themessage points at the offending field, and code is usually null.
401 authentication_error
TheAuthorization header is missing, or the key is not valid. The code is invalid_api_key.
Authorization: Bearer sk-... and that the key is active in the dashboard.
402 insufficient_credits
Your account has no remaining balance for platform models. Thecode is null.
404 not_found
The requested model or resource does not exist. Thecode is model_not_found for an unknown model id.
GET /v1/models for the live list of ids. See Models.
429 rate_limit_error
You have sent too many requests. Thecode is rate_limited.
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. Thecode is upstream_unavailable, and the message is intentionally generic.
Handling errors
Retry429 and 503, which are transient. Do not retry 400, 401, 402, or 404 without changing the request, the key, the balance, or the model.
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.