Errors

Every model API response — success or error — carries x-request-id and request-id response headers (req_<32 hex chars>). Include the value when contacting support.

Non-streaming errors

Errors are returned with a non-2xx HTTP status and a JSON body. The shape matches the request's protocol.

OpenAI-shaped paths (/models, /models/user, /chat/completions, /embeddings, /responses):

JSON

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic-shaped path (/messages):

JSON

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  },
  "request_id": "req_1f2e3d4c5b6a7988a1b2c3d4e5f60718"
}

When a model rejects a recognized parameter, HTTP 400 keeps invalid_request and identifies the parameter in error.param. For example:

JSON

{
  "error": {
    "message": "Invalid value for parameter 'temperature'.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_request"
  }
}

An unsupported field uses This model does not support parameter 'store'.. An incompatible combination uses Parameters 'tools' and 'reasoning_effort' cannot be used together with this model.. Responses errors use public paths such as reasoning.effort and text.format. Anthropic errors identify the parameter in error.message without adding param. If the parameter cannot be identified safely, param stays null and the message stays Invalid request.. Backend details never appear in these messages. A rejection before streaming starts uses this HTTP contract even with stream:true. Errors after streaming starts retain the generic SSE contract below.

Storage, cache management, and safety attribution fields can be ignored on models that do not support them: store, prompt_cache_key, prompt_cache_retention, and safety_identifier. Both store:true and store:false are ignored on models without response storage. These fields do not change output content, format, or tool behavior. Other unsupported generation controls and invalid values or combinations still fail. Unknown future fields can still return HTTP 400.

Streaming errors

When stream: true and an error occurs after the stream has already started, the error arrives as one SSE frame instead of an HTTP error status. There are three shapes, depending on the path:

/chat/completions (OpenAI Chat Completions):

Text

data: {"error":{"message":"Upstream request failed.","type":"upstream_error","param":null,"code":"provider_error"}}

/messages (Anthropic Messages):

Text

event: error
data: {"type":"error","error":{"type":"api_error","message":"Upstream request failed."},"request_id":"req_1f2e3d4c5b6a7988a1b2c3d4e5f60718"}

/responses (OpenAI Responses):

Text

event: error
data: {"type":"error","code":"provider_error","message":"Upstream request failed.","param":null}

Error codes

code (OpenAI shape) and error.type (Anthropic shape) are stable and safe to branch on. message text is not — it may change without notice.

HTTP status	`code`	OpenAI `type`	Anthropic `type`	Meaning
400	`invalid_request`	`invalid_request_error`	`invalid_request_error`	Malformed request
401	`invalid_api_key`	`authentication_error`	`authentication_error`	Missing or invalid API key
402	`insufficient_credits`	`billing_error`	`billing_error`	Prepaid credit balance is too low
403	`permission_denied`	`permission_error`	`permission_error`	Key lacks access to this model or route
404	`route_not_found`	`invalid_request_error`	`not_found_error`	Unknown path
404	`model_not_found`	`invalid_request_error`	`not_found_error`	Model id not found
405	`method_not_allowed`	`invalid_request_error`	`invalid_request_error`	Wrong HTTP method for the path
413	`request_too_large`	`invalid_request_error`	`request_too_large`	Request body exceeds the size limit
429	`rate_limit_exceeded`	`rate_limit_error`	`rate_limit_error`	Too many requests; see the `retry-after` header
502	`provider_error`	`upstream_error`	`api_error`	Upstream provider request failed
503	`overloaded`	`service_unavailable_error`	`overloaded_error`	Gateway in-flight limit reached; retry later
503	`gateway_unavailable`	`service_unavailable_error`	`api_error`	Could not reach the upstream
504	`upstream_timeout`	`timeout_error`	`api_error`	Upstream did not respond in time

Select a model with the top-level model field. Requests that select an upstream model through extra_body.model, models, or route return HTTP 400 (invalid_request). This also applies to models and route inside extra_body, provider or deployment selectors, provider credentials such as api_key or an Authorization entry in extra_headers, and fallback lists.

SDK advice

Branch on code / error.type and HTTP status, never on message. Treat 4xx as generally non-retriable (except 429, which is retriable after retry-after) and 5xx (502/503/504) as retriable with backoff.