Errors

Error shape

OpenAI-format endpoints (/v1/chat/completions, /v1/responses, /v1/models) answer errors as:

OpenAI-format error

{"error": {"code": "model_not_found", "message": "unknown model class gpt-4o; see GET /v1/models"}}

Some errors add fields next to code, such as limit and retryAt on a 429.

/v1/messages and /v1/messages/count_tokens answer in the Anthropic shape, which the Anthropic SDK reads:

Anthropic-format error

{"type": "error", "error": {"type": "authentication_error", "message": "missing or malformed install token"}}

Status	`code`	Meaning
`400`	`invalid_request`	The body does not match the endpoint's schema. The message names the field.
`400`	`invalid_json`, `invalid_body`	The body is not valid JSON, or its compression could not be decoded.
`400`	`unsupported_content`	A content part or file type the endpoint does not take. See Images and Files.
`400`, `413`, `422`	`upstream_rejected`	The provider rejected the request. The status is the provider's.
`401`	`unauthorized`	Missing, malformed, unknown or revoked token.
`404`	`model_not_found`	Unknown model class or direct model, or a class without a Claude candidate on `/v1/messages`.
`404`	`not_found`	No such endpoint.
`405`	`method_not_allowed`	Wrong HTTP method for the endpoint.
`413`	`body_too_large`	The body is over the endpoint's size limit.
`415`	`unsupported_encoding`	Unsupported `content-encoding`. `/v1/messages` takes no compression.
`429`	`rate_limit_exceeded`	The token is over one of its limits.
`429`	`pool_exhausted`	Every account that could serve the request is rate limited.
`503`	`providers_unavailable`	No candidate of the model class, or the direct model, is available.
`503`	`subscription_unavailable`	The Claude pool is unreachable.
`500`	`internal_error`	A gateway bug.

On /v1/messages, a provider error comes back with the provider's status and a generic body:

Provider error on /v1/messages

{"type": "error", "error": {"type": "api_error", "code": "subscription_upstream_error", "message": "Subscription request failed"}}

On /v1/messages and /v1/messages/count_tokens the body carries the Anthropic type for the status instead of code.

When to retry

Retry 429 after retry-after and 503 with backoff. Do not retry other 4xx errors unchanged.