Claude API Error Codes Explained: Fixing 401/403/404/429/529
Claude API Error Codes Explained: Fixing 401/403/404/429/529
It is 2 AM, the build pipeline is red, and the log shows a single line: authentication_error. Every developer integrating the Claude API knows the moment. The good news: API errors are precise — each code tells you exactly which layer failed. This guide takes the five most frequent Claude API error codes apart one by one: what each means, why it fires, the exact fix, and a fixed troubleshooting order that ends the guesswork.
What the error response looks like
Definition: Anthropic-style APIs return a consistent JSON envelope on failure: top-level type is error, inner error.type is a machine-readable category (such as authentication_error), and error.message carries a human-readable explanation. Always parse error.type first — it pins down the failure more precisely than the status code alone.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}
A detail from live testing
Through a gateway, authentication failures can be intercepted before forwarding, and the body may be short plain text (for example, a bare 401 with Invalid token) instead of the full JSON envelope. The quick test: retry once with a known-good key. If it succeeds, the endpoint and path are fine and the earlier failure was at the key layer.
401 authentication_error: the key layer
Why it fires: no key attached, a mistyped key, a revoked key — or a stale environment variable silently overriding your config.
How to fix:
- Confirm the key is sent via the
x-api-keyheader (Anthropic semantics) with no stray spaces - Run
echo $ANTHROPIC_API_KEYand check the current shell value is not an old one - Generate a fresh key in the console as a cross-check — if the new one works, the old one was genuinely dead
The most common 401 of all
Unsetting one stale environment variable resolves more than half of all 401s. Shell-exported variables take priority over config files — when both exist, the shell always wins.
403 permission_error: the permission layer
Why it fires: the key is valid but lacks access to the target resource — most often the key is restricted to certain model groups, or the account itself is suspended.
How to fix: 403 differs from 401 in one way — the key is correct but insufficient. Confirm the account status first, then confirm the target model is within the key's allowed scope. Through a gateway, check whether the gateway restricts that model; switch models or adjust the scope in the console as needed.
404 not_found_error: path and model ID
Why it fires: two possibilities — the request path is wrong, or the model ID does not exist.
Path check: the official endpoint is https://api.anthropic.com/v1/messages; through EXAIV it is https://exaiv.com/api/ai/v1/anthropic/v1/messages. The most common mistake is applying OpenAI-style paths like /v1/chat/completions to the Anthropic protocol, or dropping the /v1 segment.
Model name check: model: "claude-opus-4-8" versus a real ID that differs by one character is a 404. The available list is endpoint-side truth — the full catalog lives on the models page.
429 rate_limit_error: the throttle layer
Why it fires: request rate or concurrency exceeded quota. This is not a malfunction — it is the system saying "slow down now".
How to fix:
- Read the
retry-afterhint in the response and wait accordingly - Implement exponential backoff: 1 second first, then 2, 4, 8 — with jitter so clients do not re-sync
- Long term: lower concurrency, merge requests, or add client-side token-bucket rate limiting
429 versus 529
429 means "you are too fast" — on the caller, fixed by backoff. 529 means "upstream is busy" — not on the caller, fixed by waiting. Neither is solved by an immediate retry.
529 overloaded_error: upstream overload
Why it fires: the upstream service is temporarily overloaded and cannot accept new requests within the time limit. It is a Claude-specific code (the OpenAI semantics have no equivalent) and passes through compatible endpoints unchanged.
How to fix: exponential backoff usually recovers within seconds to tens of seconds. For availability-sensitive pipelines, configure a fallback model for degradation — one of the core benefits of a gateway: switching models is a one-string change, no new keys, no re-auth work.
Other codes at a glance
| Code | error.type | Meaning | Handling |
|---|---|---|---|
| 400 | invalid_request_error | Malformed body or invalid parameter | Read the message; usually missing max_tokens or malformed messages |
| 413 | request_too_large | Body over the size limit | Trim context or split the document |
| 500 | api_error | Upstream internal error | Backoff and retry; investigate only if persistent |
The fixed troubleshooting order
| Layer | Check | Tool |
|---|---|---|
| ① Key | Current shell value, revoked? | echo $ANTHROPIC_API_KEY |
| ② URL | Path complete (with /v1)? | Compare with the 404 section above |
| ③ Model ID | Character-exact against the list | Models page |
| ④ Throttle/overload | Status 429/529 | Backoff and retry |
| ⑤ Network | Proxy, firewall | Cross-check on another network |
One habit that saves the most time: hit the endpoint with bare curl first, before touching any application code. If curl works and your code does not, the bug is in your client layer. If curl fails too, walk the table above. This compresses average debugging from half an hour to under five minutes.
Wrap it once: a retry-aware request helper
Rather than sprinkling retry logic across call sites, wrap the endpoint once and let every feature inherit it. A sound helper does four things in order: send with the current key and full URL; classify the failure by error.type (authentication/permission are non-retryable, rate and overload are retryable); apply exponential backoff with jitter only to the retryable class, up to a maximum attempt count; and surface the final error with the model ID and attempt count attached so logs are self-explanatory.
Teams that adopt this pattern report a second-order benefit: when a new error category appears upstream, the classification table lives in exactly one place, so the fix propagates to every consumer at once. The same helper becomes the natural home for timeout budgets per environment — short timeouts for interactive paths, generous ones for batch jobs — without touching call sites again.
Monitoring: turn errors into a dashboard
Counting errors by error.type over time converts this article into an operations dashboard. Three series are enough for most teams: authentication errors (should be flat zero — any spike means a leaked or rotated key somewhere), rate-limit errors (your capacity planning curve), and 529/500 (upstream health from your vantage point). Alert on the first, forecast with the second, and only page a human for sustained failures of the third.
One nuance when routing through a gateway: the gateway's own auth rejections appear as short-text 401s rather than JSON envelopes, so parse defensively — treat any non-2xx as an error event and classify by body shape, not by assumed structure. This keeps the dashboard honest across both direct and gateway paths.