Claude Code 429 error: what it means and how to fix it

A Claude Code 429 rate limit error means one of your limits ran out, not that Claude is down. Which one is in the text: You've hit your session limit · resets 3:45pm is your plan's 5-hour window, Request rejected (429) is an API key's per-minute rate limit, and enforced_spend_limit_reached is the organization's monthly spend cap.

Before that line reached you, Claude Code had already tried again. Its error reference says it "retries transient failures up to 10 times with exponential backoff before showing you an error" (Claude Code docs), and 10 is the default of CLAUDE_CODE_MAX_RETRIES (environment variables). What's on screen is the error that didn't clear by itself.

Which 429 is it? Read the message#

The first words of the error tell you which limit it is. Rows one to five are quoted from Claude Code's error reference and row six from Anthropic's rate-limit page, both read on 22 October 2026 (Claude Code docs, Claude docs).

529 Overloaded is missing from the table on purpose: "A 529 is not your usage limit and doesn't count against your quota" (Claude Code docs).

Why it happens: how the limits work#

Three kinds of limit answer with a 429.

• Plan limits on Pro, Max and Team: a 5-hour session window and a weekly limit, both shared across models, plus model-specific limits for Opus and Sonnet (when the 5-hour window starts and resets).
• API rate limits, per organization and per model, in requests, input tokens and output tokens per minute. Anthropic uses a token bucket, so "your capacity is continuously replenished up to your maximum limit, rather than being reset at fixed intervals", and 60 requests per minute "might be enforced as 1 request per second" (Claude docs). Parallel subagents that start together make exactly that kind of burst.
• A monthly spend cap per tier, which on 22 October 2026 stood at $500 for Start, $1,000 for Build and $200,000 for Scale. Hitting it returns the same rate_limit_error as a rate limit, told apart by error.details.error_code reading enforced_spend_limit_reached. There's no retry-after header on it, and retrying fails until access resumes (Claude docs).

A spend limit you set yourself, below the cap, is not a 429. It comes back as HTTP 400 invalid_request_error, starting You have reached your specified API usage limits (Claude docs).

How to fix a Claude Code 429#

1. Run /status to see which credential is active. Claude Code's docs warn that "a stray ANTHROPIC_API_KEY in your environment can route requests through a low-tier key". Claude Code prefers a set key over your logged-in subscription: an interactive session asks you to approve it once, and claude -p uses it without asking (environment variables). To go back to the plan, unset ANTHROPIC_API_KEY, delete the export line from ~/.zshrc or ~/.bashrc, restart claude and /login.
2. On a plan limit, /usage shows the bars and the reset times. You've hit your Opus limit or Sonnet limit clears with /model and the other family. The session and weekly limits are shared across models, so another model won't help there.
3. On an API rate limit, retry-after is "the number of seconds to wait until you can retry the request" (Claude docs). Wait that long, then stagger the burst so parallel subagents don't start in the same second.
4. On the spend cap, ask for a higher tier on the Console's Rate limits page or raise your own limit under Billing. If neither happens, access comes back at 00:00 UTC on the 1st.
5. In CI, CLAUDE_CODE_RETRY_WATCHDOG=1 makes Claude Code retry 429 and 529 capacity errors indefinitely instead of failing (Claude Code docs). Add CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000 to give up on a request after 30 minutes (Claude Code v2.1.295 or later, environment variables). A spend-limit 429 fails at once either way.
6. Or move the work. /usage-credits turns on usage credits, a bigger plan raises the limits, and another account you own has limits of its own. Claude limit reached: what to do has the rest.

How Shuriken handles it#

Shuriken launches every Claude Code chat with ANTHROPIC_BASE_URL set to a small proxy on your own computer, one per chat. Every 429 reaches the proxy before Claude Code, and the wait it asks for decides what happens.

• Under a minute, the proxy holds the request and resends it after the retry-after seconds, or every 15 seconds when there are none, for at most 5 minutes. Claude Code and its subagents see a slow request.
• A minute or more, plan usage limits included: Shuriken hot swaps the chat to another of your sources with room, even before your switch point, and sends the held request there. The subagents go with it. A Switched to … card names the account that took over (source switching).

Before 3.0.0 we got the second case wrong. A plan limit that arrived without retry-after looked to the proxy like any throttle: it waited 15 seconds, tried again, and kept at it until the 5 minutes ran out. Then Claude Code got You've hit your limit, and a Workflow's subagents died on it while another account had room. Since 3.0.0, released on 12 October 2026, the proxy reads the 429's anthropic-ratelimit-unified-status header first. rejected means the plan's limit, so the chat moves, and a limit that names Fable stops only Fable.

If an account is refused outright, with an expired sign-in or disabled access, the chat moves to another usable source instead of ending; that came in 3.3.0 (A refused account no longer ends your chat). If every source is out, the chat shows one pause card ("Paused: no Claude source has usage left") and carries on by itself once a source has room again.

Use accounts you own and are entitled to use; providers' terms may not allow sharing a subscription sign-in. Download Shuriken.