← Blog · 2026-10-24

Claude Code API Error? Fixes for 429 Rate Limit, 529 Overloaded, 500 and Usage Limit Reached

30-second test: read the exact wording, then run /status. A 5xx or 529 is Anthropic's side: check status.claude.com and start at cause 1. Request rejected (429) or Credit balance is too low is your API key or cloud project: start at cause 5. You've hit your session limit, weekly limit, Opus limit or spend limit is your plan: start at cause 9.

Most Claude Code runtime errors are an API status code with a friendlier message on top. Before you see one, Claude Code has already retried: transient failures get up to 10 retries with exponential backoff, and the spinner shows Retrying in Ns · attempt x/y while it does. So when an error reaches you, a plain "try again" has already been tried a few times.

The four families look similar but mean very different things:

• 500 and other 5xx: something failed inside the API. It isn't your prompt, settings or account.
• 529 Overloaded: the API is at capacity across all users. It isn't your usage limit and doesn't count against your quota.
• 429: a rate limit on your API key, Console workspace or cloud project, or a short server-side throttle.
• Usage or spend limit: your subscription's allowance or your usage-credits budget ran out.

Server errors and overload: 4 causes

1. API Error: 500 Internal server error. The full message reads This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com. Check the status page for an incident, wait a minute and send again. Your original message is still in the conversation, so for a long prompt you can just type try again instead of pasting it again. If a proxy or load balancer answered instead, you'll see its status and page title, such as API Error: 502 Bad Gateway. If it keeps happening with no posted incident, run /feedback so Anthropic can look at the request. One special case: if ANTHROPIC_BASE_URL points at an LLM gateway and every request fails with a 5xx, the gateway may be rejecting the tool search fields Claude Code sends by default. Test by setting ENABLE_TOOL_SEARCH=false and trying again.
2. API Error: Repeated 529 Overloaded errors. The API is temporarily at capacity, and Claude Code already retried several times. Capacity is tracked per model, so the fastest fix is /model and a different model. Claude Code sometimes says this outright, for example Opus is experiencing high load, please use /model to switch to Sonnet. Otherwise check status.claude.com and try again in a few minutes. Don't upgrade your plan or buy credits over a 529: it isn't a quota problem.
3. No fallback model is set, so an overload stops your turn. You can tell Claude Code to switch models on its own when the primary is overloaded or unavailable. For one session: claude --fallback-model sonnet,haiku. To keep it, add "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"] to your settings file (the flag wins over the setting). The switch lasts for the current turn only, a chain holds at most three models, and Claude Code shows a notice when it switches. /status doesn't show the chain, so the notice is the first sign it's working. Rate-limit, billing and authentication errors never trigger a fallback, so this helps with 529s and 5xx errors, not with 429s or usage limits.
4. API Error: Server is temporarily limiting requests (not your usage limit). A short server-side throttle that has nothing to do with your plan. Claude Code tells it apart from a real limit because the response lacks your plan's quota headers. Since v2.1.199 it's retried automatically with backoff however you sign in; on older versions a claude.ai subscription session failed on the first one. Run claude --version, update with claude update if you're behind (Claude Code not updating helps if that fails), then wait briefly and retry.

429 rate limits: 4 causes

5. API Error: Request rejected (429). You hit the rate limit set for your API key, Amazon Bedrock project or Google Cloud project. The message adds this may be a temporary capacity issue, but if it repeats, the limit is the real problem. Check your provider console for the active limits and request a higher tier if needed. Cut concurrency too: many parallel subagents multiply your requests, and for high-volume scripted runs a smaller model via /model helps. If a proxy or gateway sends its own 429 page, the text after the · is that page's title, such as Too Many Requests.
6. A stray ANTHROPIC_API_KEY is sending your requests through a low-tier key. This is the most common surprise 429 for people on Pro or Max. Run /status: if an API key row is active, Claude Code is billing and rate-limiting through that key, not your subscription. The same key is behind Credit balance is too low on a paid plan, because the Console organization it belongs to has no prepaid credits left. Fix: unset ANTHROPIC_API_KEY, delete the export line from your shell profile, open a new terminal and run claude, then /login with your subscription if you haven't. env | grep ANTHROPIC catches keys loaded by direnv, dotenv plugins or IDE terminals. Claude Code login not working walks through every credential that can override your login, in priority order.
7. Your Console org or workspace is over its per-minute limits. The API measures requests per minute, input tokens per minute and output tokens per minute for each model class, and a 429 tells you which one you exceeded. When the 429 carries a retry-after header, wait that many seconds before retrying. Capacity refills continuously (a token bucket) rather than resetting on the minute, so short pauses help. Two details matter for Claude Code. First, cached input tokens don't count toward the input-token limit on most models, so steady sessions that reuse the prompt cache go further than the raw numbers suggest. Second, Console sign-ins get an auto-created "Claude Code" workspace; with custom rate limits its traffic counts toward your organization's limits, an admin can set a workspace rate limit on its Limits page, and its limits can come back as a 429. A sudden sharp jump in an organization's usage can also hit acceleration limits, which Anthropic says to avoid by ramping traffic gradually. For small teams of 1-5 users, Anthropic's costs page suggests 200k-300k tokens and 5-7 requests per minute per user.
8. An unattended or CI run gives up too soon. By default Claude Code retries 10 times (CLAUDE_CODE_MAX_RETRIES, capped at 15) and then stops. For CI jobs and other unattended sessions, set CLAUDE_CODE_RETRY_WATCHDOG=1: it retries 429 and 529 capacity errors indefinitely, backing off up to 5 minutes between attempts or until the reset time a rate-limit response carries, and raises retries for other transient errors to 300, roughly three hours. It still fails at once on a 429 that reports a spend limit or exhausted usage credits. To cap the wait per request, set CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS (v2.1.295 or later). Without the watchdog, CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS (default 500, up to 32000) spreads 529 retries over a longer window. Going the other way, lower CLAUDE_CODE_MAX_RETRIES in scripts that should fail fast.

Usage and spend limits: 4 causes

9. You've hit your session limit or You've hit your weekly limit. Subscription plans include a rolling allowance, and Claude Code blocks requests until the reset time in the message, for example resets 3:45pm. Both limits are shared across all models, so switching models won't help. Usage counts against the session and weekly windows at the same time, so one heavy burst, like a large fan-out of subagents, can use up the week before the session window resets. Run /usage to see your limits and reset times. Since v2.1.234, an interactive session signed in with claude.ai waits and continues the task on its own after the reset: keep the session open and you'll see Continuing automatically at 3:45pm · esc to cancel. Press Esc to cancel, or use /rate-limit-options to choose. To keep going right now, /usage-credits buys extra usage on Pro and Max, or asks your admin on Team and Enterprise.
10. You've hit your Opus limit or You've hit your Sonnet limit. These apply only to that model family, so /model and a model outside the family keeps you working. Expect the first request after the switch to cost more: each model has its own prompt cache, so it re-reads the whole conversation with no cache hits.
11. A spend limit, not a usage window. You've hit your monthly spend limit, individual spend limit, org's monthly spend limit or team's shared budget means the request would bill to usage credits and those credits hit a cap. On Pro and Max, raise it in Settings > Usage on claude.ai or with /usage-credits; on Team and Enterprise, an admin raises it in Organization settings > Usage. If the message also names a reset time for your plan's window, you can simply wait. A related one: Usage credits required for 1M context is an entitlement check, not an exhausted quota. Run /model and pick the variant without [1m], or turn usage credits on and restart Claude Code. Setting CLAUDE_CODE_DISABLE_1M_CONTEXT=1 hides the 1M variants from the picker.
12. Your sessions burn through usage faster than they should. Claude Code sends the whole conversation with every request, and every round of tool results is another request, so a one-line question in a session that's been open all day still pays for the whole history. Cache misses after a break, /loop and scheduled tasks, agent teammates and compacting a huge context all add up. On a paid plan, /usage attributes usage to skills, subagents, plugins and MCP servers and recommends fixes, such as trimming a large CLAUDE.md. The cheapest habits: /clear between unrelated tasks (it costs nothing, while /compact is itself a large request), Sonnet for everyday work, and lower /effort for simple jobs. Our guide to Claude Code context filling up fast has nine more ways to keep each request small. To see a limit coming instead of hitting it, show the rate_limits.five_hour and rate_limits.seven_day percentages in your status line; our free status line builder writes the script for you. For a full walkthrough of where plan usage goes and how to keep working once you're blocked, see Claude Code usage limit reached.

Still stuck?

If the error says Request timed out, Unable to connect to API or Connection refused, it's a network or proxy problem rather than a limit: run curl -I https://api.anthropic.com from the same shell, and check that a leftover ANTHROPIC_BASE_URL isn't pointing at a proxy that's no longer running. If a subagent stopped with Agent terminated early due to an API error, match the text after the colon to the sections above. For anything else, run /feedback to send the transcript to Anthropic, claude doctor for a diagnostic, and check status.claude.com. If Claude Code just sits on Retrying or Waiting for API response with no error, or freezes mid-task, see Claude Code stuck or not responding. If claude won't start at all, see Claude Code command not found, and if a key in your env block seems ignored, settings not applying shows which file wins. Certificate errors such as UNABLE_TO_GET_ISSUER_CERT_LOCALLY and proxy setup are covered in our proxy and SSL certificate errors guide.

Facts on this page come from Anthropic's Claude Code docs on errors, managing costs, model configuration, environment variables, interactive mode, the status line and the CLI reference, plus the Claude API pages on errors and rate limits. This guide isn't affiliated with Anthropic.

Most usage-limit pain comes from setup: a bloated CLAUDE.md, no permission presets and expensive defaults. Our Claude Code Power Config Pack has 6 lean CLAUDE.md templates, permission presets and 8 tested safety hooks, $6 with the launch code while it lasts.