Anthropic / Claude API Error Explainer
Search every Anthropic Claude API error by HTTP status, error type, or message text. The key distinction this tool highlights: a 429 rate_limit_error is your quota running hot (back off), while a 529 overloaded_error is Anthropic's servers under pressure — both require retries, but for completely different reasons.
How to use the Anthropic / Claude API Error Explainer
Type any fragment — HTTP status, Anthropic error type string, or keywords from the error message — into the search box. The list filters live across all fields.
Each card shows:
- Status — the HTTP status code returned by the API.
- Type — the
error.typefield in the JSON response body. - Cause — what triggered the error.
- Fix — the concrete resolution.
- Retryable — whether an automatic retry will succeed.
The centerpiece distinction: 429 vs 529. A 429 rate_limit_error is your application exceeding your account's throughput limits — slow down. A 529 overloaded_error is Anthropic's infrastructure under load — it is completely independent of your limits and will resolve on its own. Both are retryable, but with a 529 there is nothing wrong with your code or account.
Anthropic API error structure
Anthropic errors follow a consistent JSON envelope: {"type":"error","error":{"type":"...","message":"..."}}. The error.type field is the canonical identifier — use it in your error-handling switch statements, not the HTTP status alone, because some statuses (particularly 429) have distinct meanings.
The most operationally significant distinction in the Anthropic API is 429 rate_limit_error vs 529 overloaded_error. A 429 means your account's per-minute or per-day token/request limits are exceeded — the fix is to slow down, honor the retry-after response header, and implement exponential back-off. A 529 is a non-standard HTTP status code that Anthropic uses specifically to signal server-side capacity issues. It has nothing to do with your quota; Anthropic's infrastructure is temporarily saturated. The correct response to both is retry with back-off, but only with a 429 should you also reconsider your throughput architecture.
Unlike OpenAI's quota-exhausted 429, Anthropic does not use a separate error code for billing blocks within a 429. If you have exhausted your credits, you will typically receive a 403 permission_error. Always inspect error.type and error.message together for the most precise diagnosis.
Common use cases
- Distinguishing 429 from 529 — the #1 operational question when Claude responses fail; this reference makes the distinction instant.
- Retry logic design — identify exactly which error types to retry and which to surface as hard failures to the user.
- Authentication debugging — quickly separate a wrong API key (401) from a permission issue (403) during setup.
- Prompt size planning — understand the 413 request_too_large threshold so you can size chunks appropriately before hitting it in production.
- On-call runbook — a 529 during peak hours is Anthropic's problem, not yours; this reference helps on-call engineers escalate correctly.
Frequently asked questions
What is the difference between 429 and 529?
rate_limit_error means your application is sending too many tokens or requests per minute relative to your account limits — you must slow down. A 529 overloaded_error means Anthropic's servers are temporarily over capacity — it is unrelated to your limits and will resolve itself. Both require retry with back-off, but only 429 indicates a need to reduce your throughput.How do I implement retry logic for Anthropic errors?
retry-after header value. For 500 and 529, retry up to 3-5 times. Never retry 400, 401, 403, or 404.