If Claude Code shows 500, repeated 529, or “the response above may be incomplete,” do not paste the task again. A failed response is not proof that no work happened. Claude Code may have completed file edits or tool calls before the stream broke, and replaying the full request can repeat them.
Classify the error, wait for the service path to recover, reopen the same session, and reconcile real state before sending continue. 500 maps to api_error; repeated 529 maps to shared overloaded_error; a mid-response notice means completed blocks remain but the final block may be missing. That third branch is the duplicate-work risk.
Repeated 529 is the key trap: Claude Code documents it as overload, not your personal usage limit, and not quota you should try to buy your way out of. Read the exact terminal line first, then use this route board.
| Exact wording you see | Treat it as | First move | Verify on the same path | Go deeper when |
|---|---|---|---|---|
API Error: 500 or api_error before output starts | service-side internal error | Check Claude Status and wait briefly | Same session, route, and model | It persists while no incident is posted |
Repeated API Error: 529 or overloaded_error before output starts | capacity overload across users | Check status and wait; switch model only if acceptable | Same session and route after a cool-down | It repeats after status and route checks |
Server error mid-response, Connection closed mid-response, or Response stalled mid-stream | partial turn; completed blocks were retained | Do not resend the whole task; inspect retained output and actual state | Resume the same session and send continue only after reconciliation | You cannot tell whether a tool or external write completed |
429 or rate_limit_error | API key rate limit | Check retry-after, Console limits, model limits, and active API route | Retry only after the limit window or route correction | Headers or Console still point to exhausted limits |
Server is temporarily limiting requests, session limit, or weekly limit | Claude Code usage window or temporary throttle | Cool down or check the plan/session window | Resume the same workflow after the window changes | The message names a plan or usage window |
| The plan looks wrong or limits do not match your account | route override | Run /status and check for ANTHROPIC_API_KEY or proxy overrides | Confirm the intended subscription or API-key route | The same route still fails with a clean branch |
Start With the Branch, Not the Theory
Claude Code's own error reference says runtime errors map to the underlying Claude API, and that the CLI already retries transient failures before it shows many of these messages. That means the visible terminal line is not the beginning of the incident. It is the point where automatic retry has already failed enough times that you need a branch decision.
That is why the first useful question is not "is Claude down?" or "am I out of quota?" It is "which documented class does this line belong to?" The answer changes the first move. A 500 asks you to check status, wait briefly, and retry the same message before escalating with request details. A repeated 529 asks you to treat capacity as the first owner and avoid quota conclusions. A true 429 asks you to inspect the API key or provider limits. A session or weekly limit asks you to wait for the window or check usage. A route mismatch asks you to verify auth before drawing plan conclusions.
The public status boundary also needs a timestamp. At the August 4, 2026 check, Claude Status showed all systems operational, including Claude API and Claude Code, while its history listed resolved model-error incidents from August 3. That does not prove your current failure is local. It shows why recovery starts with live status and then moves immediately to same-session state verification.
Use the route board as a router. If a row points to a deeper branch, take that handoff after the branch is clear. Do not make one mixed-symptom flow answer every detailed recovery job.
The 500 Branch: Internal Error, Status, One Retry
Anthropic's API error reference maps HTTP 500 to api_error. Claude Code's error reference shows the terminal example as an internal server error and says it is not caused by your prompt, settings, or account. That boundary matters because it stops the wrong fixes early. Do not start by editing shell profiles, buying more usage, or reinstalling the CLI.
The safe sequence is small:
- Check Claude Status for active incidents.
- Wait briefly, then retry the same command or message once.
- Keep the same model and auth route during the verification attempt.
- If there is no posted incident and the same path still fails, use
/feedbackor the support route with request details.
Keep this branch narrower than a full 500 recovery path. If your exact symptom is persistent API Error: 500, use the dedicated Claude Code API Error 500 guide after the route board. The deeper 500 path spends more time on login, resumed-session, and auth-route branches. The router's job is only to stop you from treating 500 as a rate-limit or 529 problem.
The important verification phrase is "same path." If you switch model, change auth, rewrite the command, and clear your environment all at once, a later success no longer tells you what worked. One small action, then the same failing path, gives you a usable signal.
The 529 Branch: Overload, Not Your Usage Limit
Claude Code's error docs are unusually direct about repeated 529: the API is temporarily at capacity across users, Claude Code has already retried before showing the message, and a 529 is not your usage limit and does not count against quota. That is the single most important correction for this mixed topic.
The first move is not to upgrade. The first move is:
- Check status for capacity notices.
- Try again in a few minutes.
- Use
/modelto switch only when the task can tolerate a different model and Claude Code's model-specific capacity message makes that route reasonable. - Verify the same session and route after the short cool-down.
If repeated 529 keeps coming back after those checks, open the dedicated Claude Code overloaded error guide. That page owns the deeper overload recovery path, including green-status persistence and route checks.
The wrong move is calling 529 a rate limit. In casual conversation, users often say "rate limited" when a request is blocked. Operationally, 529 overloaded_error and 429 rate_limit_error are different branches. Treating 529 like quota exhaustion sends you toward billing changes, key rotation, or plan upgrades before the documented overload path has even been tested.
Resume the Same Session Before You Reconstruct the Task
Claude Code's current error reference treats a mid-response failure differently from an error that happens before generation begins. Completed response blocks stay in the conversation; an interrupted final text or tool-call block is discarded. The UI tells you that the response may be incomplete because resending the request could run the same tools twice.
In an interactive session, read the response that remains on screen. If it contains a completed edit, command result, test output, or deployment step, count that as evidence to verify—not as a promise that every intended step finished. Once the service recovers, reply continue in that conversation only after you have checked state.
If the process exited, return to the same project directory and use the official session controls:
bashclaude --continue claude --resume
claude --continue opens the most recent session for the current directory. claude --resume opens the picker so you can choose the correct conversation. The session documentation says a resumed session restores conversation history, including tool calls and results. That is more reliable than starting a fresh session and describing the outage from memory.
Do not resume the same session in two terminals. Claude Code documents that messages can interleave in one transcript. If you need an alternative path, fork the session deliberately instead of creating an accidental second executor.
Audit Side Effects Before You Send Continue
The conversation tells you what Claude attempted. The system of record tells you what actually happened. Reconcile both, starting with the cheapest local evidence and moving outward only as needed.
| Possible side effect | Evidence to inspect | Safe decision |
|---|---|---|
| Direct file edit | git status --short, git diff -- <path>, file contents | Keep the existing edit or reverse it intentionally; do not ask for the same edit again |
| Shell command changed files | working tree, generated files, command output, timestamps | Treat the command as potentially completed because checkpointing may not track it |
| Test, build, or migration still running | terminal/process list, lock files, test report, database migration table | Wait or stop it deliberately; do not launch a duplicate process |
| Commit or branch operation | git status, git log -1 --oneline, current branch | Continue from the observed Git state, not from the last sentence in chat |
| CI, deployment, issue, API, or database write | provider dashboard, run ID, deployment ID, record state, idempotency key | Verify at the external owner; never infer “failed” from a broken response stream |
For a Git repository, a compact local pass is often enough to identify the next move:
bashgit status --short git diff --stat git diff git log -1 --oneline
These commands do not prove remote state. If the interrupted turn could have opened a pull request, deployed a build, created a ticket, charged a payment, or changed a database, inspect that system directly. Use its request ID, run ID, or idempotency key when available. Starting a new local session does not cancel work already accepted by an external service.
After reconciliation, give the resumed session a bounded instruction:
textBefore doing more work, summarize the completed tool calls from the interrupted turn and compare them with the current working tree and any external state I provide. Do not rerun commands or make external changes. Identify exactly one next step and wait for my confirmation.
This prompt makes the continuity task explicit. It does not replace your verification; it forces the resumed conversation to use the evidence already present instead of reconstructing the task as if nothing happened.
Know What Checkpoints Can and Cannot Recover
Claude Code checkpointing saves snapshots for changes made by its direct file-editing tools and keeps them with the session, so /rewind can help after you resume. It is useful when a completed edit is wrong or you want to restore code and conversation to an earlier prompt.
It is not a transaction log. The official limitations exclude files changed by Bash commands, most background subagent edits, manual or concurrent edits outside the session, and some linked paths. Checkpoints also cannot rewind deployments, APIs, databases, messages, payments, or other remote effects. Use Git for durable file history and the external system's own audit trail for remote state.
The safe rule is simple: rewind only after you know what you are undoing. A blind rewind followed by a blind replay can produce a different duplicate instead of restoring certainty.
The Rate-Limit Branches: 429, Temporary Limiting, Session Windows
"Rate limit" can mean at least three different things inside Claude Code.
The first is true API 429 rate_limit_error. Anthropic's API error docs map 429 to rate_limit_error, and the Claude Code error reference says Request rejected (429) can come from the API key, Amazon Bedrock project, or Google Vertex AI project. That branch belongs to API limits, provider limits, concurrency, model choice, and sometimes retry-after behavior. It does not belong to the 529 overload playbook.
The second is Claude Code's temporary limiting message: Server is temporarily limiting requests (not your usage limit). Claude Code documents this as a short-lived throttle that is retried automatically before being shown. The recovery is brief waiting and a same-path try again, plus status if it persists. It is not proof that your plan is exhausted.
The third is a real usage window: session limit, weekly limit, Opus limit, or another plan-window message that names a reset. That branch belongs to usage monitoring, /usage, plan reset timing, and possibly extra usage or a plan decision. If that is your branch, use the Claude Code rate limit reached guide or the broader Claude Code usage limits diagnosis guide.
The practical difference is evidence. True API 429 evidence often lives in headers, provider Console limits, rate buckets, and the active credential route. Plan-window evidence lives in Claude Code's usage wording and reset time. Temporary limiting evidence lives in the exact short-lived throttle message. Do not collapse those into one fix.
The Route Override Branch: Check Auth Before Blaming the Plan
Anthropic's Claude Help document on API key environment variables says Claude Code prioritizes environment variable API keys over authenticated subscriptions. It also says /status can show which authentication method is active. That makes route verification part of the recovery flow, not a side quest.
This is the branch to test when the error does not match your account expectation. Maybe you thought you were using a Claude subscription, but ANTHROPIC_API_KEY is exported in your shell. Maybe a proxy or provider route is active. Maybe the same phrase "rate limit" is coming from a project with lower API limits rather than from the subscription path you had in mind.
Use a non-secret route check:
- Run
/statusinside Claude Code. - Check whether
ANTHROPIC_API_KEYis set without pasting the key anywhere. - Confirm whether the active route is subscription auth, direct Anthropic API, Bedrock, Vertex, or a proxy.
- Retry the same request on the route you actually intended to use.
If removing an unexpected key or correcting the route changes the result, route mismatch was the real problem. If the same intended route still fails with the same documented branch, you now have cleaner evidence for the right guide or support path.
Verify Recovery Before You Escalate
Anthropic's API docs say error responses include a top-level request_id, and every API response includes a request-id header. Keep those when they are available. Claude Code also gives you branch-specific commands such as /status, /model, /usage, and /feedback, depending on the problem surface.
Before escalating, collect the smallest useful packet:
- exact terminal line, including
500,529,429, or the full limiting message - time and timezone of the failure
- Claude Status result at that time
- active route from
/status - model in use and whether
/modelwas changed - same-path retry result
- request ID or feedback context when available
That packet is intentionally short. "Claude Code is broken" is not actionable. "All systems operational on April 20, same API-key route, repeated 529 after cool-down, request ID attached" is actionable. "Status green, API Error 500 persists on the same command after one retry" is actionable. "429 returned with active API-key route and provider Console limits exhausted" is actionable.
The escalation boundary is this: once you have matched the branch, taken the smallest branch-specific action, and verified the same path, stop improvising. More random retries usually destroy evidence. A clean support packet preserves it.
FAQ
Is Claude Code 529 a rate limit?
No. Claude Code documents repeated 529 as overload, not your usage limit. True API rate limiting is the 429 rate_limit_error branch. Temporary limiting and plan-window messages are separate again.
What should I do first for Claude Code API Error 500?
Check Claude Status, wait briefly, and retry the same command or message once. If no incident is posted and the same path still fails, keep request details and move to the dedicated 500 guide or /feedback.
What if Claude Status is green but Claude Code still fails?
Green status only rules out the live-incident branch. You still need to check the exact error, active auth route, model, and same-path retry result. A green page does not prove the failure is your fault.
How do I know whether an API key is overriding my subscription?
Run /status in Claude Code and check whether ANTHROPIC_API_KEY is set in your shell or environment. Anthropic's help docs say environment variable API keys take priority over authenticated subscriptions.
Should I upgrade my plan when I see 529?
No, not as a first move. A repeated 529 is an overload branch. Upgrade decisions belong to explicit plan-limit or usage-window messages, not to overloaded_error.
Is it safe to paste the same task after an outage?
Not when Claude Code says the response may be incomplete. Completed blocks and tool calls may already be present. Resume the same session, inspect the retained response, reconcile local and external state, and then send a bounded continue instruction.
Does /rewind undo commands and deployments?
No. Checkpoints cover supported direct file edits, not Bash changes or remote side effects. Verify Git, processes, deployments, APIs, and databases at their actual owners.
Which page should I read next?
Use the branch you identified. Persistent 500 goes to the Claude Code API Error 500 guide. Repeated overload goes to the Claude Code overloaded error guide. True API or usage limits go to the Claude Code token usage guide, rate-limit reached guide, or usage limits diagnosis guide.
