API Error Code Decoder

Decode any Anthropic API error in seconds

Every Anthropic API error carries two useful pieces of information: an HTTP status code and an error type string like invalid_request_error or overloaded_error. Together they tell you exactly what went wrong and, crucially, whether the request is safe to retry. This decoder maps each code and type to its precise meaning, the common causes, and an ordered fix. It runs entirely in your browser - no API key, no request, nothing you enter is ever sent anywhere.

The most important split is retryable vs not. A 429, 500, or 529 is worth retrying with backoff - the request was fine, the timing or the server was not. A 400, 401, 403, 404, or 413 will fail identically no matter how many times you retry, because the request itself is wrong. Retrying a non-retryable error just wastes time and, on rate limits, can dig the hole deeper.

The status codes, precisely

• 400 invalid_request_error - your request is malformed or has a bad/missing field. Not retryable; fix the request.
• 401 authentication_error - your API key is missing, wrong, or revoked. Not retryable; fix the key.
• 403 permission_error - valid key, but no permission for that model/action. Not retryable; fix access.
• 404 not_found_error - the resource does not exist, usually a mistyped model name or wrong URL. Not retryable; fix the reference.
• 413 request_too_large - the request body exceeded the size limit. Not retryable; shrink or split it.
• 429 rate_limit_error - you hit a rate or usage limit. Retryable after a wait, with backoff.
• 500 api_error - a server-side error on Anthropic's end. Retryable with backoff.
• 529 overloaded_error - the service is temporarily at capacity. Retryable with backoff.

How to read the error body, not just the code

Anthropic errors return a JSON body with a type and a human-readable message. The status code tells you the category; the message usually names the exact problem. A 400 will typically tell you which field is invalid. A 404 will hint that the model name is unknown. Always read the message string, not just the number - it turns 'something is wrong' into 'max_tokens exceeds the model limit' or 'model not found'. The decoder above gives you the category and the common causes; the message narrows it to the specific one.

Building retries that behave

1. Only retry the retryable codes: 429, 500, 529. Treat 4xx (except 429) as terminal.
2. Use exponential backoff: wait 1s, then 2s, then 4s, doubling each attempt.
3. Add jitter - a small random offset - so many clients do not retry in lockstep.
4. Honor the retry-after header on a 429 when present; it beats your computed delay.
5. Cap the number of attempts and surface the error rather than looping forever.
6. Log the status and type so recurring failures are easy to diagnose later.

The auth and permission errors people trip on

401 and 403 look similar but mean different things. A 401 means the server does not know who you are - the key is missing, wrong, or revoked; fix it by confirming the key is set correctly and regenerating it if needed. A 403 means the server knows who you are but you are not allowed to do this - the key is valid but lacks access to that model, feature, or endpoint; fix it by checking your account's access, not the key itself. Confusing the two sends you fixing the wrong thing. Also: never hardcode or log your key, and never expose it behind an unauthenticated endpoint - load it from an environment variable and keep it server-side.

From decoding errors to shipping reliably

Once you can read a status code and instantly know 'retry this' or 'fix the request', API errors stop being blockers and become quick routing decisions. The developers who ship reliable things on the Anthropic API bake this in: correct retry logic for the three retryable codes, clear handling for the terminal ones, and never a raw key exposed to the client. The Claude Code Club curriculum covers building on the API the right way, from robust error handling to safe key management.