D1 · Agentic Architecture › Cluster 6 · Reliability

6.3 · Retry with Backoff & Error Codes

The SDK already retries — know what it retries and what it won't

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"}],
)
🔑 The default is 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.

CodeMeaningRetryable?Note
400invalid_request🔴 NoFix the request; identical failure on retry
401authentication🔴 NoBad/missing API key
403permission🔴 NoKey lacks access
404not_found🔴 NoWrong resource
408request timeout🟢 YesSDK auto-retries
409conflict🟢 YesSDK auto-retries
413request_too_large🔴 NoShrink the payload
429rate_limit🟢 YesHas a retry-after header; the one retryable 4xx
500api_error🟢 YesServer-side; SDK auto-retries
529overloaded🟢 YesAPI busy; back off and retry

DIAGRAM Should this failure be retried?

flowchart TD E([Request fails]) --> Q1{"Status code?"} Q1 -->|"408 · 409 · 429
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
⚠️ If you do hand-roll backoff (e.g. custom orchestration outside the SDK), the SDK is already retrying underneath — stacking loops multiplies your effective retry count and can amplify a 429 storm. Prefer tuning max_retries over wrapping the call.

EXAM TRAPS

Trap: "Retry the 400 with backoff." → No. 4xx except 429 are not retryable; a 400 is your malformed request and fails identically. Retrying wastes calls.
Trap: "Write a retry loop for 429s." → The SDK already retries 429/5xx/529 with exponential backoff. Adjust max_retries instead of reimplementing it.
Trap: Detecting errors by parsing the message string. → Use the typed exceptions (RateLimitError, APIStatusError, APIConnectionError). Strings change; types don't.
Trap: Forgetting 529 overloaded is retryable. → It's the API being busy, not your request — back off and retry, same bucket as 5xx.

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.