Errors
Check HTTP status first, then decode the protocol-specific error. Not every response has a string error.code.
Gateway errors outside Anthropic
{"error":{"code":404,"type":"invalid_request_error","message":"Model not found","gateway_code":"MODEL_NOT_FOUND"}}error.code is the numeric HTTP status; error.gateway_code is the detailed machine identifier. X-Gateway-Trace-ID is a response header.
Anthropic Messages / count_tokens errors
{"type":"error","error":{"type":"invalid_request_error","message":"Model not found"},"request_id":"gw-..."}This shape has error.type, error.message and request_id, without a guaranteed gateway_code or string code. Sanitized upstream errors may instead use error.code = UPSTREAM_REQUEST_FAILED or UPSTREAM_MEDIA_FETCH_FAILED. Handle all three shapes without expecting private upstream details.
Common gateway identifiers
| HTTP | gateway_code | Meaning |
|---|---|---|
| 400 | MODEL_REQUIRED | Missing model |
| 400 | INVALID_REQUEST_BODY | Invalid speech request; other validation depends on mapping |
| 400 | PROTOCOL_TRANSFORM_FAILED / AUDIO_FORMAT_UNSUPPORTED / PROTOCOL_STREAM_UNSUPPORTED | Mapping, format or streaming mismatch |
| 401 | UNAUTHORIZED / INVALID_API_KEY | Missing or invalid key |
| 402 | INSUFFICIENT_BALANCE / KEY_BUDGET_EXCEEDED / PROJECT_BUDGET_EXCEEDED | Insufficient balance or exhausted budget |
| 402 / 403 | PROJECT_DISABLED | Model/list requests use 402; file requests use 403 |
| 403 | MODEL_NOT_ALLOWED | Model not allowed by this key |
| 404 | MODEL_NOT_FOUND / MODEL_API_NOT_SUPPORTED | Unavailable model or no mapping for this protocol |
| 404 | UNSUPPORTED_ENDPOINT / VIDEO_TASK_NOT_FOUND | Unknown path or invalid video handle |
| 405 | METHOD_NOT_ALLOWED | Unsupported HTTP method |
| 413 | REQUEST_TOO_LARGE | Body too large or cannot be read by the endpoint |
| 429 | RATE_LIMIT_EXCEEDED / ROUTE_CAPACITY_EXCEEDED | Key rate limit or exhausted route capacity |
| 500 | API_KEY_LOOKUP_FAILED / MODEL_QUERY_FAILED / MODEL_LIST_QUERY_FAILED / MODEL_RULE_CHECK_FAILED / MAPPING_QUERY_FAILED | Database/internal lookup failure |
| 502 | UPSTREAM_CONNECT_ERROR / UPSTREAM_TRANSPORT_ERROR / PROTOCOL_RESPONSE_TRANSFORM_FAILED | Connection, transport or response conversion failure |
| 503 | UPSTREAM_UNAVAILABLE / RATE_LIMIT_STATE_UNAVAILABLE | No available upstream or unavailable rate state |
| 504 | UPSTREAM_TIMEOUT | Upstream timed out; work may already have started |
For unknown identifiers retain status and Trace for support. Do not infer unsupported codes. File-specific errors are documented in the files API.
Retry handling
402 requires fixing balance, budget or project state; 401/403 require credentials or permissions. Respect Retry-After for 429 and use bounded backoff for safely retryable 5xx requests. SSE can report errors after HTTP 200; stop and retain the Trace.