D5 · Context & Reliability › Cluster 5 · Reliability: Errors & Retries

5.1 · API Error Codes (4xx vs 5xx, 429, 529)

Read the status before reacting

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.

Codeerror.typeMeaningRetryable?
400invalid_request_errorMalformed request — bad JSON, missing field, roles don't alternate🔴 No — fix it
401authentication_errorAPI key missing, malformed, or revoked🔴 No
403permission_errorKey valid but lacks access to that model/resource🔴 No
404not_found_errorBad endpoint or model ID (e.g. claude-opus-4.8 vs -4-8)🔴 No
413request_too_largeBody exceeds the limit (Messages API: 32 MB)🔴 No — shrink it
429rate_limit_errorToo many requests/tokens per minute🟢 Yes — honor retry-after
500api_errorUnexpected internal error at Anthropic🟢 Yes — backoff
529overloaded_errorAPI temporarily overloaded (high traffic across all users)🟢 Yes — backoff
🔑 The error body is always JSON: {"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).

⚠️ Don't retry a 4xx (except 429). A 400 or 404 is a bug in your request — retrying the same bytes burns quota and never succeeds. Fix the payload instead.

DIAGRAM The status routes the reaction

flowchart TD A["Non-2xx response"] --> C{"Which family?"} C -->|"4xx (except 429)"| FIX["🔴 Fix the request
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-after so 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)
Let the SDK do the retrying it's good at (transient 429/5xx with backoff), and reserve your own handling for the terminal 4xx it correctly refuses to retry.

EXAM TRAPS

Trap: "Retry the 400 a few times." → A 400 invalid_request_error is a bug in your request (bad JSON, non-alternating roles). Retrying identical bytes never succeeds — fix the payload.
Trap: Treating 429 and 529 as the same thing. → 429 = your rate limit (comes with retry-after); 529 = Anthropic overloaded across all users. Both retry, but they're different causes.
Trap: "429 is a 4xx, so it's a client error I can't retry." → 429 is the only retryable 4xx. The request was valid; you just sent too many. Wait and retry.
Trap: String-matching 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.)