CONCEPT The SDK auto-retries — you rarely hand-roll backoff
The Anthropic SDK automatically retries transient failures with exponential
backoff. Retryable status codes are 408, 409, 429,
5xx, and 529, plus connection errors. The default is max_retries=2,
configurable per-client or per-request.
import anthropic # Configure retries at the client level... client = anthropic.Anthropic(max_retries=4) # ...or per-request, without a new client: resp = client.with_options(max_retries=5).messages.create( model="claude-opus-4-8", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], )
max_retries=2. Set it via
Anthropic(max_retries=…) or client.with_options(max_retries=…). You usually
don't write your own retry loop for API calls — the SDK does exponential backoff for you.CONCEPT Retryable vs. not
The dividing line: transient faults are worth retrying; a 4xx client error (except 429) is a problem with your request and will fail identically on retry — retrying it just wastes calls and can cascade.
| Code | Meaning | Retryable? | Note |
|---|---|---|---|
400 | invalid_request | 🔴 No | Fix the request; identical failure on retry |
401 | authentication | 🔴 No | Bad/missing API key |
403 | permission | 🔴 No | Key lacks access |
404 | not_found | 🔴 No | Wrong resource |
408 | request timeout | 🟢 Yes | SDK auto-retries |
409 | conflict | 🟢 Yes | SDK auto-retries |
413 | request_too_large | 🔴 No | Shrink the payload |
429 | rate_limit | 🟢 Yes | Has a retry-after header; the one retryable 4xx |
500 | api_error | 🟢 Yes | Server-side; SDK auto-retries |
529 | overloaded | 🟢 Yes | API busy; back off and retry |
DIAGRAM Should this failure be retried?
5xx · 529 · conn err"| R["🟢 Retryable
SDK backs off & retries"] Q1 -->|"4xx except 429
(400/401/403/404/413)"| N["🔴 Not retryable
fix the request"] R --> Q2{"Retries exhausted
(max_retries)?"} Q2 -->|No| R Q2 -->|Yes| L["Climb the ladder →
fallback (6.4) / escalate (6.5)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef no fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef nx fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; class R ok; class N no; class L nx;
CODE Catch typed exceptions, don't string-match
The SDK raises typed exceptions. Branch on the type — matching on error-message text is brittle and breaks silently when wording changes.
import anthropic client = anthropic.Anthropic() # default max_retries=2 already active try: resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, messages=[{"role": "user", "content": prompt}], ) except anthropic.RateLimitError: # 429 — SDK already retried & gave up escalate_or_queue() # honour retry-after; shed load except anthropic.APIConnectionError: # network / transport failure fallback() # the request never reached the API except anthropic.APIStatusError as e: # any non-2xx after retries if e.status_code < 500: # 4xx (not 429): our bug — do NOT retry log_and_raise(e) else: fallback() # 5xx/529 exhausted → degrade
max_retries over wrapping the call.EXAM TRAPS
max_retries instead of reimplementing it.RateLimitError, APIStatusError, APIConnectionError). Strings change; types don't.PRACTICE
Q1 · Your call fails with 413 request_too_large. Retry?
No — 413 is not retryable. The payload is too big and will fail identically. Shrink the input (trim context, chunk, or drop attachments), don't retry.
Q2 · What's special about 429 among the 4xx codes?
It's the only retryable 4xx. It carries a retry-after header, and the SDK
auto-retries it with backoff. All other 4xx (400/401/403/404/413) are client errors you must fix.
Q3 · You need up to 5 automatic retries on one specific critical call, but the default elsewhere. How?
Use client.with_options(max_retries=5).messages.create(...) for that call. It
returns a copy with the override applied per-request, leaving the base client's default (2) untouched.