Automatic retries

Claude Code retries transient failures up to 10 times with exponential backoff before showing you an error. It doesn't always retry a failure that arrives partway through Claude's response. When you see one of the errors on this page, Claude Code has already made whatever retries apply to that failure; the lists below say which failures get the full budget, which get a smaller one, and which get none.

Claude Code retries these failures:

• Server errors, overloaded responses, and request timeouts that arrive before any of Claude's response has streamed.
• Dropped connections. When a connection drops partway through a request before Claude has completed any part of its response, including its thinking, Claude Code re-issues the request with the same backoff and the turn continues, even if some text had already started streaming. When it drops after Claude has finished thinking but before it has started any text or tool call, Claude Code instead re-issues the request up to two times in quick succession, and ends the turn with Connection lost before a response was produced if the connection keeps dropping at that point.
• A connection that Claude Code detects was broken by your computer going to sleep partway through a request. Claude Code counts it as a dropped connection under the rules above; once the retry label names the specific reason, it reads Connection lost while your computer was asleep, and if the turn ends after Claude has finished thinking but before any text or tool call, the message reads Your computer went to sleep before a response was produced.
• A stalled response stream, when the response headers have arrived but none of Claude's response has arrived, or when Claude has finished thinking but hasn't started any text or tool call: Claude Code aborts the stalled connection and re-issues the request at most once, outside the 10-attempt budget above. If the response stalls a second time after Claude has finished thinking but before any text or tool call, Claude Code ends the turn with The response stalled before a response was produced.
• A streaming request the API never answers with response headers, on a connection where the first-byte deadline runs: Claude Code aborts it at the deadline and re-sends it at most once per model request, within the retry budget, then ends the turn with No response from API if that attempt goes unanswered too. On other connections, the request waits out API_TIMEOUT_MS. When you set CLAUDE_CODE_RETRY_WATCHDOG, the one-retry cap doesn't apply.
• Temporary 429 throttles, but not a gateway's spend-limit 429, which isn't a throttle; see Spend limit reached.
  • When you're signed in with a claude.ai subscription, this includes 429 throttles that don't carry your plan's quota headers. Before v2.1.199, Claude Code retried those throttles only for API key and Enterprise sign-ins.
• A request rejected because the input plus max_tokens exceeds the context limit. Re-sending it unchanged would fail the same way, so Claude Code retries with a reduced max_tokens, and stops retrying and compacts instead in two cases:
  • When no reduction can fit, for example when the conversation itself nearly fills the context window.
  • When a retry can't shrink max_tokens any further. Before v2.1.218, Claude Code could re-send a reduced request that still didn't fit, such as when the extended thinking budget exceeded the remaining context, until the retry budget ran out.
• An expired or missing Google Cloud credential on Google Cloud's Agent Platform, or AWS credentials that fail to load on your machine. Claude Code discards its cached credentials and retries up to two times, then reports the error so you can re-authenticate right away, as described under Could not load AWS or Google Cloud credentials. Before v2.1.228, Claude Code retried a failing Google Cloud credential through the full retry budget before showing the error.
• A 401 or 403 from the Anthropic API, directly or through an LLM gateway, while an apiKeyHelper script supplies the credential. Claude Code re-runs the script and retries with its fresh output, within the full retry budget. When the script itself fails on the re-run, Claude Code shows Your apiKeyHelper script is failing instead.

Before v2.1.227, Connection lost before a response was produced read Connection closed while thinking, before producing a response and The response stalled before a response was produced read Response stalled while thinking, before producing a response.

Claude Code doesn't retry these failures:

• A TLS certificate validation failure, such as a TLS-inspecting proxy, a missing NODE_EXTRA_CA_CERTS bundle, or an expired certificate. Claude Code reports the error on the first attempt, so you can fix the certificate setup right away; see SSL certificate errors. Claude Code still retries transient TLS conditions such as a handshake timeout. Before v2.1.199, Claude Code retried certificate failures through the full retry budget before showing the error.
• A server error, dropped connection, or stalled stream that arrives after Claude has completed a block of text or a tool call, or has started one after finishing its thinking, but before it finishes the response. Claude Code doesn't re-run the request, because that could execute the same tool calls twice. It keeps what Claude completed, runs any tool calls Claude finished, and continues the turn from their results. For what you see in an interactive session and in a non-interactive one, read The response above may be incomplete. Before v2.1.199, Claude Code discarded the partial output and reported the whole turn as an error when a server error arrived mid-stream.
• A failure that arrives after Claude has finished the response: nothing needs retrying, so Claude Code keeps the complete response and ends the turn normally.
• An Amazon Bedrock streaming response with an unexpected content-type, because the gateway or proxy rewriting the response would rewrite the retry the same way. Requires Claude Code v2.1.208 or later.
• A non-streaming retry of a failed streaming request that gets a success status but no Claude API message in the body. Claude Code ends the turn with that error.
• A request that your organization's policy check denied, which surfaces as an API Error: line carrying the denial message. Your organization's administrators set up the check with Inference hooks, a Claude Enterprise feature, and the message ends with the instructions they configured, or by default tells you to contact them. Claude Code doesn't re-send the denied request to the same model or to a fallback model, because the denial is about the request's content rather than the model. Before v2.1.239, Claude Code could re-send a denied request, without streaming or on a configured fallback model, before showing you the denial.

What you see while Claude Code retries or waits

While retrying, the spinner shows a Retrying in Ns · attempt x/y countdown after an error label. The label names the specific reason from the first attempt for failures you can act on right away: the network is down, a TLS handshake failed, or you hit a rate limit. For other errors it reads API error at first. As of v2.1.198 it switches to the specific reason from the third attempt, or on the final attempt when CLAUDE_CODE_MAX_RETRIES allows fewer than three; earlier versions switch only on the final attempt.

As of v2.1.198, the usual spinner tip is suppressed during retries. Once the error reason is revealed, if the failure is a 529 overload the line below the countdown also names where to check service status: status.claude.com on the Anthropic API, or the provider or gateway host named in the message on other configurations.

If no data arrives on the response stream for 20 seconds while a request is still pending, the spinner shows Waiting for API response · will retry in … · check your network before any retry has started. The request hasn't failed yet: the countdown runs to the point where Claude Code aborts the stalled connection. After the abort, what you see depends on how far the response had got:

• Before Claude has completed a block of text or a tool call, or started one after finishing its thinking, Claude Code retries the request or ends the turn with an error. Automatic retries says which stalls it retries and how many times.
• After Claude has completed a block of text or a tool call, or started one after finishing its thinking, but before Claude has finished the response, Claude Code keeps what Claude completed, continues the turn from any tool calls Claude finished, and shows The response above may be incomplete. In a non-interactive session, and for a subagent's response in any session, Claude Code may first prompt Claude to continue the response; that entry says when it does and when you still see the notice there.
• After Claude finished the response, Claude Code ends the turn normally.

The banner clears on its own once data resumes or a retry succeeds. If it reappears on every attempt, treat it as a network issue. Before v2.1.185, the banner appeared after 10 seconds with different wording.

While Claude is consulting the advisor, the banner appears after 90 seconds without data instead of 20, because a long advisor review can send nothing for well over 20 seconds. Before v2.1.214, the 20-second threshold applied during advisor calls too, so the banner appeared during advisor reviews even when nothing was wrong.

Tune retry behavior

You can tune retry behavior with these environment variables:

Variable	Default	Effect
CLAUDE_CODE_MAX_RETRIES	10	Number of retry attempts. Capped at 15 as of v2.1.186; as of v2.1.199 CLAUDE_CODE_RETRY_WATCHDOG raises the default and removes the cap. Lower it to surface failures faster in scripts.
CLAUDE_CODE_RETRY_WATCHDOG	unset	Set to 1 in unattended sessions such as CI jobs to retry 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. Claude Code fails at once on a 429 that reports a spend limit or exhausted usage credits, even one from a gateway spend cap that resets on a schedule. Before v2.1.239, the watchdog retried these indefinitely. On v2.1.199 or later it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on CLAUDE_CODE_MAX_RETRIES if you set that variable explicitly.
API_TIMEOUT_MS	600000	Per-request timeout in milliseconds. Raise it for slow networks or proxies. It also caps how long Claude Code waits for response headers, described in No response from API.
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS	unset	Deadline in milliseconds for the first response byte of a streaming request. Requires Claude Code v2.1.242 or later. For how Claude Code picks the deadline when this is unset, see No response from API.