If Claude Code shows 500, 529, or a rate-limit message, do not start by retrying harder or changing plans. These are different recovery branches: 500 maps to api_error, repeated 529 maps to overloaded_error, and true API rate limiting maps to 429 rate_limit_error.
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 | service-side internal error | Check Claude Status, wait briefly, retry the same command once | Same command, same auth route, same model | It persists while status is green or no incident is posted |
Repeated API Error: 529 or overloaded_error | capacity overload | Check status, wait, or switch model only if that is acceptable for the task | Same session and route after a short cool-down | It repeats after status and route checks |
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 date. At the April 20, 2026 check, Claude Status showed all systems operational, including Claude API and Claude Code, while the status history also listed resolved same-day model error incidents and a resolved April 15 incident affecting Claude.ai, API, and Claude Code. That does not prove your current failure is local. It proves why the recovery sequence starts with status, then immediately requires same-path 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.
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.
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.