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):

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

Anthropic-shaped path (/messages):

{
  "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:

{
  "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.. For recognized sampling restrictions, the message states the accepted condition: Parameter 'temperature' must be 1 unless 'reasoning_effort' is 'none' with this model.. A single restricted sampling parameter keeps its own error.param. When the Chat restriction lists logprobs, top_p, and top_logprobs together, error.param names the reasoning effort field and the message lists all three parameters. Recognized errors can include supported values or a correction, such as This model does not support forced 'tool_choice'. Use 'auto'. Invalid model selection identifies model; invalid tool history identifies messages on Chat/Messages and input on Responses. A rejected format type identifies response_format on Chat and text.format on Responses. These messages describe the rejection without changing request parameters. Responses errors use public paths such as reasoning.effort and text.format. Anthropic errors identify the parameter in error.message without adding param. Messages errors name recognized native fields, such as output_config.effort, and map stop to stop_sequences. For a rejected combination with an ambiguous effort field, they retain the conflict and identify the native control without guessing an effort field. When the backend establishes the original reasoning field, combination errors name both native fields. Errors that identify only an ambiguous or OpenAI-only field keep Invalid request.. 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):

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

/messages (Anthropic Messages):

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

/responses (OpenAI Responses):

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.

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.