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, /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"
}

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.

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

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.

Non-streaming errors

Streaming errors

Error codes

SDK advice