DocsAPI referenceErrors

Errors

The three error envelopes, category-to-HTTP mapping, and common errors.

The gateway presents three API shapes, and error bodies match the shape of the API you called — decided by path: /v1/messages* uses the Anthropic shape, /v1beta/* the Google shape, everything else the OpenAI shape. This keeps every SDK's error parsing working as expected.

The three error envelopes

OpenAI

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Anthropic

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

Google

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}

Categories & status codes

Category	HTTP	OpenAI `type`	Anthropic `type`	Google `status`
Authentication	401	`invalid_request_error`	`authentication_error`	`UNAUTHENTICATED`
Permission	403	`invalid_request_error`	`permission_error`	`PERMISSION_DENIED`
Not found	404	`invalid_request_error`	`not_found_error`	`NOT_FOUND`
Unsupported endpoint	404	`invalid_request_error`	`not_found_error`	`INVALID_ARGUMENT`
Invalid request	400	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
Rate limit	429	`rate_limit_error`	`rate_limit_error`	`RESOURCE_EXHAUSTED`
Quota / balance	402	`insufficient_quota`	`billing_error`	`RESOURCE_EXHAUSTED`
Payload too large	413	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
Upstream failure	502	`api_error`	`api_error`	`UNAVAILABLE`
Overloaded	503	`server_error`	`overloaded_error`	`UNAVAILABLE`
Internal error	500	`api_error`	`api_error`	`INTERNAL`

Common errors

Message id	HTTP	Meaning & what to do
`key_missing` / `key_invalid`	401	Missing or invalid API key — check your auth header.
`key_disabled` / `key_expired` / `key_ip_denied`	403	The key is disabled, expired, or your IP is not allowlisted.
`key_quota_exhausted`	402	The key's spending limit is exhausted — wait for the reset or raise the limit.
`balance_exhausted`	402	Insufficient account balance — top up and retry.
`rpm_exceeded` / `concurrent_exceeded`	429	RPM or concurrency limit exceeded — back off and retry.
`model_missing`	400	The request is missing the `model` field.
`model_not_found` / `model_disabled`	404	The model does not exist or has been retired — check the id against Models.
`no_upstream_for_model`	404	No upstream currently serves this model — retry later or contact the administrator.
`moderation_blocked`	403	Blocked by content moderation — revise the request and try again.
`body_too_large`	413	The body exceeds this endpoint's size limit — compress inlined media or use another endpoint.
`upstream_timeout` / `upstream_unreachable` / `all_upstreams_down`	502	Upstream timed out, is unreachable, or all upstreams are tripped — back off and retry.
`server_busy`	503	The gateway's in-flight capacity is full — retry shortly.

Error messages are localized to the account's preferred language (before auth, Accept-Language; default English). Branch on the HTTP status and the type/status field, never on the message text.

For concrete retry and backoff patterns, see Error handling & retries.