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

> A Claude Code 429 rate limit error means you hit an allowance, not an outage: your plan's window, your API tier or a spend cap. Which one, and what to do.

Source: https://shuriken.sh/guides/claude-code-429-rate-limit-error

A Claude Code 429 rate limit error means one of your limits ran out, not that Claude is down: on a subscription your 5-hour, weekly or model limit, with an API key your tier's per-minute rate limit or a monthly spend cap.

By Shuriken Updated 27 October 2026 5 min read

**Contents**

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](https://code.claude.com/docs/en/errors)), and 10 is the default of CLAUDE_CODE_MAX_RETRIES ([environment variables](https://code.claude.com/docs/en/env-vars)). 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](https://code.claude.com/docs/en/errors), [Claude docs](https://platform.claude.com/docs/en/api/rate-limits)).

| What you see | What it means | How long |
| --- | --- | --- |
| You've hit your session limit · resets 3:45pm | Your plan's 5-hour window is full | Until the time shown |
| You've hit your weekly limit · resets Mon 12:00am | Your plan's weekly limit is full | Until the time shown |
| You've hit your Opus limit or Sonnet limit | That model family's limit only | Until the time shown, or switch model |
| API Error: Server is temporarily limiting requests (not your usage limit) | A short server-side throttle | Moments; Claude Code retries it |
| API Error: Request rejected (429) | Your API key's (or Bedrock or Google Cloud project's) rate limit | Seconds to a minute |
| rate_limit_error with enforced_spend_limit_reached | Your API organization's monthly spend cap | Until the 1st of next month, 00:00 UTC |

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](https://code.claude.com/docs/en/errors)).

## 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](https://shuriken.sh/guides/claude-5-hour-limit-explained)).
- 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](https://platform.claude.com/docs/en/api/rate-limits)). 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](https://platform.claude.com/docs/en/api/rate-limits)).

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](https://platform.claude.com/docs/en/api/rate-limits)).

Shuriken moves a running chat to another of your own accounts when one reaches its limit, on every device.

[Download](https://shuriken.sh/download)

## How to fix a Claude Code 429 #

- 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](https://code.claude.com/docs/en/env-vars)). To go back to the plan, unset ANTHROPIC_API_KEY, delete the export line from ~/.zshrc or ~/.bashrc, restart claude and /login.
- 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.
- On an API rate limit, retry-after is "the number of seconds to wait until you can retry the request" ([Claude docs](https://platform.claude.com/docs/en/api/rate-limits)). Wait that long, then stagger the burst so parallel subagents don't start in the same second.
- 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.
- In CI, CLAUDE_CODE_RETRY_WATCHDOG=1 makes Claude Code retry 429 and 529 capacity errors indefinitely instead of failing ([Claude Code docs](https://code.claude.com/docs/en/errors)). 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](https://code.claude.com/docs/en/env-vars)). A spend-limit 429 fails at once either way.
- 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](https://shuriken.sh/guides/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](https://shuriken.sh/features/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](https://shuriken.sh/blog/how-switching-picks-the-next-account)). 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](https://shuriken.sh/download).

Try the free tool: [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude)

Share

[X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-429-rate-limit-error&text=Claude%20Code%20429%20error%3A%20what%20it%20means%20and%20how%20to%20fix%20it)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-429-rate-limit-error)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-429-rate-limit-error&t=Claude%20Code%20429%20error%3A%20what%20it%20means%20and%20how%20to%20fix%20it)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-429-rate-limit-error&title=Claude%20Code%20429%20error%3A%20what%20it%20means%20and%20how%20to%20fix%20it)[E-mail](mailto:?subject=Claude%20Code%20429%20error%3A%20what%20it%20means%20and%20how%20to%20fix%20it&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-429-rate-limit-error)

## Sources

- [Claude Code docs: Error reference](https://code.claude.com/docs/en/errors) (accessed 22 October 2026)
- [Claude docs: Rate limits](https://platform.claude.com/docs/en/api/rate-limits) (accessed 22 October 2026)
- [Claude Code docs: Environment variables](https://code.claude.com/docs/en/env-vars) (accessed 25 October 2026)

## Frequently asked questions

**Does a 429 mean Claude is down?**

No. It means you reached a limit: the plan's window, the key's per-minute rate or a spend cap. Problems on Anthropic's side come back as 529 Overloaded, and a 529 doesn't count against your usage.

**Why do I get a 429 when I still have usage left on my plan?**

Check /status first. If it shows an API key, Claude Code is sending requests on that key's tier, not your Pro or Max plan, because a set ANTHROPIC_API_KEY wins even when you're logged in. Run unset ANTHROPIC_API_KEY and restart claude to go back to the plan.

**How long should I wait after a 429?**

Whatever the error names. You've hit your session limit · resets 3:45pm means 3:45pm, and an API key's 429 carries retry-after in seconds while its bucket refills continuously. A spend-cap 429 has no retry-after at all and holds until 00:00 UTC on the 1st of next month, unless someone raises the cap.

**Does Claude Code retry 429 errors automatically?**

Yes for temporary throttles. Claude Code makes up to 10 tries with exponential backoff before the error appears, and CLAUDE_CODE_MAX_RETRIES changes the 10. Retrying doesn't clear a spend-limit or used-up-credit 429, which isn't a throttle.

Source switching

One account runs dry. The next one takes over.

Add the Claude, Codex and Gemini accounts you own. At your switch point, your chats move to another of them and keep going.

[Download](https://shuriken.sh/download)

[Other platforms](https://shuriken.sh/download#main)

## Keep reading

- [How to switch Claude accounts without logging out: Guide 27 Oct 2026 7 min read Three ways to use several Claude accounts in Claude Code without /logout and /login: one config per account, a switcher CLI, or a harness.](https://shuriken.sh/guides/switch-claude-accounts-without-logging-out)
- [Claude's weekly limit, explained: Guide 27 Oct 2026 6 min read Paid Claude plans have a weekly limit on top of the 5-hour window. When it resets, how model limits fit in, and why parallel agents reach it in two days.](https://shuriken.sh/guides/claude-weekly-limit-explained)
- [How to check your Claude Code usage: Guide 27 Oct 2026 6 min read To check Claude Code usage, type /usage or open Settings › Usage on claude.ai. Both read one pool: your 5-hour session and your weekly limit.](https://shuriken.sh/guides/check-claude-code-usage)
- [Codex usage limits explained (2026): Guide 27 Oct 2026 5 min read How Codex limits work on ChatGPT Plus and Pro: the 5-hour and weekly windows, the 2026 changes, checking yours with /status, and using several accounts.](https://shuriken.sh/guides/codex-usage-limits)
- [Anthropic API rate limit tiers: how to move up: Guide 27 Oct 2026 5 min read Anthropic API rate limit tiers set a monthly spend cap and per-minute limits. The tiers in October 2026, how to move up, and what Claude Code hits first.](https://shuriken.sh/guides/anthropic-api-rate-limit-tiers)
- [Claude Code 529 overloaded: why it happens, what to do: Guide 27 Oct 2026 5 min read A 529 overloaded error means Anthropic's API is at capacity, not that your quota ran out. Why Claude Code shows it, what helps and what doesn't.](https://shuriken.sh/guides/claude-code-529-overloaded)
- [/compact vs /clear in Claude Code: when to use which: Guide 27 Oct 2026 5 min read Use /clear when you start a new task and /compact when one task has a long history. A decision table, what auto-compact keeps and what a summary loses.](https://shuriken.sh/guides/claude-code-compact-vs-clear)
- [Claude Code for beginners: your first hour: Guide 27 Oct 2026 6 min read Claude Code for beginners: it needs a paid Claude plan or a Console account, installs with one command, and is safest if you commit to git first.](https://shuriken.sh/guides/claude-code-for-beginners)

## Free tools

- [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude)
- [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)