Errors
Error shapes, codes and idempotency.
Errors use the shape of the endpoint you called and always include request_id. Messages never reveal upstream vendors, hosts or model names.
| HTTP | OpenAI type / code | Anthropic error.type | Meaning |
|---|---|---|---|
| 400 | invalid_request_error / invalid_request, unsupported_parameter, capability_not_supported | invalid_request_error | Malformed body, or a field this model cannot honour (param names it). |
| 401 | authentication_error / invalid_api_key | authentication_error | Missing, invalid or revoked key. |
| 402 | insufficient_balance | billing_error | Available credits are below the estimated cost. Top up or lower max_tokens. |
| 402 | spend_limit_reached | billing_error | A spend cap was reached: one you set on the API key (daily or monthly), on the coding session, or on the project (monthly) — see spend caps — or the limit on what a new account may spend in the 24 hours after its first payment. When the cap resets at a known time, retry-after says when. |
| 403 | permission_error | permission_error | Missing scope, suspended project, or a request from an address outside the key's IP allowlist (ip_not_allowed). |
| 404 | invalid_request_error / model_not_found | not_found_error | Unknown model for this key. |
| 409 | invalid_request_error / idempotency_conflict | — | Same Idempotency-Key with a different body. |
| 413 | request_too_large | request_too_large | Body over 32 MB. |
| 429 | rate_limit_error / rate_limited | rate_limit_error | Retry after the retry-after header. |
| 502 / 503 / 504 | api_error | api_error, overloaded_error (529), timeout_error | Upstream failed, is overloaded or timed out. Retryable; nothing is charged. |
Idempotency
Non-streaming requests may carry an Idempotency-Key header. A retry with the same key and body within 24 hours returns the stored response with idempotency-replayed: true and is not charged again.