Retry Logic
Claude Code implements exponential backoff with up to 10 retries. Different error codes have different retry strategies, and unattended mode has special handling for long-running tasks.
10 max retries (default) 500ms base backoff delay 5min max backoff delay 6h unattended mode cap
Retry flow
1
API call fails
Error received from the Anthropic API. 2
Check error code
Different codes have different retry budgets and delays. 3
Calculate backoff 500ms → 5min
Exponential backoff: 500ms base, doubles each attempt, capped at 5 minutes. 4
Wait and retry
Wait the calculated delay, then retry the request. 5
Max retries reached?
After 10 attempts (default), surface the error to the user. Error code behavior
| Error | Name | Max retries | Notes |
|---|---|---|---|
| 529 | Overloaded | 3 | Only for foreground queries. Background queries are not retried on 529. |
| 429 | Rate limited | 10 | Uses retry-after headers from the response if present, otherwise uses exponential backoff. |
| Other 5xx | Server errors | 10 | Standard exponential backoff applies. |
Unattended mode (internal)
Used internally for long-running automated tasks. Unattended mode has different retry behavior:
- · Indefinite retries (no max retry limit)
- · 30-second heartbeat keeps the process alive
- · 6-hour hard cap prevents runaway processes
- · Not available in standard user sessions
i Backoff is per-session, not global
The retry counter resets between separate API calls. If Claude makes 10 tool calls in a
session, each one has its own independent 10-retry budget. A single slow API response
doesn't consume retries from other operations.