CONCEPT The HTTP status is the whole diagnosis
Every non-2xx response from the Messages API carries an HTTP status code and a JSON body with
a stable error.type. The status splits cleanly into two families that demand opposite reactions:
4xx = you sent something wrong (fix the request — retrying the identical bytes will fail
forever), and 5xx = Anthropic had a problem (the request was fine; retry with backoff).
The one 4xx that breaks this rule is 429 — the request was valid, you just sent too many, so
it is retryable. Read the code first; it tells you whether to fix, retry, or give up.
| Code | error.type | Meaning | Retryable? |
|---|---|---|---|
| 400 | invalid_request_error | Malformed request — bad JSON, missing field, roles don't alternate | 🔴 No — fix it |
| 401 | authentication_error | API key missing, malformed, or revoked | 🔴 No |
| 403 | permission_error | Key valid but lacks access to that model/resource | 🔴 No |
| 404 | not_found_error | Bad endpoint or model ID (e.g. claude-opus-4.8 vs -4-8) | 🔴 No |
| 413 | request_too_large | Body exceeds the limit (Messages API: 32 MB) | 🔴 No — shrink it |
| 429 | rate_limit_error | Too many requests/tokens per minute | 🟢 Yes — honor retry-after |
| 500 | api_error | Unexpected internal error at Anthropic | 🟢 Yes — backoff |
| 529 | overloaded_error | API temporarily overloaded (high traffic across all users) | 🟢 Yes — backoff |
{"type":"error","error":{"type":"…","message":"…"},"request_id":"req_…"}.
Log the request_id (also returned as the request-id response header) — it's what Anthropic support traces.CONCEPT 429 vs 529 — two very different overloads
These are the two codes the exam loves to confuse. 429 rate_limit_error is
your ceiling — you exceeded your organization's requests- or tokens-per-minute limit (or hit an
acceleration limit from ramping traffic too fast). 529 overloaded_error is
Anthropic's ceiling — the whole API is saturated across all users, nothing to do with your quota.
Both are retryable, but 429 comes with a retry-after header telling you exactly how long to wait,
while 529 just needs exponential backoff. A couple of edge codes also appear: 402
billing_error, 408/504 timeout_error, and 409
conflict_error (resolve the conflict, then retry).
DIAGRAM The status routes the reaction
400/401/403/404/413"] C -->|"429 rate_limit"| WAIT["🟠 Wait retry-after,
then retry"] C -->|"5xx: 500 / 529"| BACK["🟢 Retry with
exponential backoff"] FIX -.->|"retrying won't help"| DEAD["Surface to caller"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class BACK ok; class WAIT gate; class FIX bad; class DEAD bad;
CODE Branch on the status, not the message string
Use the SDK's typed exceptions — never grep the error text. Catch most-specific first, and
separate the retryable branch from the terminal one.
import anthropic client = anthropic.Anthropic() try: msg = client.messages.create(model="claude-opus-4-8", max_tokens=1024, messages=[{"role": "user", "content": "Hi"}]) except anthropic.NotFoundError: # 404 — bad model id; DON'T retry raise except anthropic.RateLimitError as e: # 429 — retryable wait = int(e.response.headers.get("retry-after", "60")) backoff_and_retry(wait) except anthropic.APIStatusError as e: # any other non-2xx if e.status_code >= 500: # 500 / 529 — retryable backoff_and_retry() else: # 400 / 401 / 403 / 413 — terminal log(e.request_id, e.message); raise
TRADE-OFFS Retry-everything vs. classify-then-retry
✅ Classify by status, then retry
- 4xx fails fast — user sees the real bug
- Only 429/5xx consume retry budget
- Honors
retry-afterso you back off correctly
⚠️ Blindly retry every error
- Simpler code, one catch-all
- But: a 400/404 retries forever, burning quota
- Hides the real fix (bad model id, oversized body)
EXAM TRAPS
invalid_request_error is a bug in
your request (bad JSON, non-alternating roles). Retrying identical bytes never succeeds — fix the payload.retry-after); 529 = Anthropic overloaded across all users. Both retry, but they're different causes.error.message to classify. → Message text can change.
Branch on the HTTP status / typed exception class and the stable error.type.PRACTICE
Q1 · Which of 400, 429, 500, 529 should you retry, and how?
Retry 429, 500, 529. For 429, wait the retry-after seconds. For 500/529, use
exponential backoff. 400 is not retryable — it's a malformed request you must fix.
Q2 · A request returns 404 not_found_error. First thing to check?
The model ID (and endpoint path). 404 usually means a typo like claude-opus-4.8
instead of claude-opus-4-8, or a deprecated/removed model. Retrying won't help — correct the string.
Q3 · You're getting 529s in a burst. What does it mean and what do you do?
529 overloaded_error means the API is temporarily overloaded across all users — not
your quota. Back off exponentially and retry; optionally shift some load to a less-loaded model. (If you
instead saw 429 from a sharp usage spike, ramp traffic up gradually to avoid acceleration limits.)