Rate Limit Reached: Claude Code Fixes That Work

The rate limit reached Claude Code error means you exhausted one of two different budgets: your subscription's usage allowance (a rolling 5-hour session window plus a weekly cap) or the API's per-minute limits on requests and tokens. Check which one fired with /usage or the 429 response, then wait for the reset, switch to a lighter model, or trim context.

We hit this message regularly while running this site with Claude Code, and the frustrating part is that it's really five different limits wearing one costume. The fix that works for a capped session does nothing for a per-minute token limit, and vice versa. Below: how to tell which limit you actually hit, and the fixes ordered from cheapest to most expensive.

What the rate limit reached Claude Code error actually means

Claude Code sits on top of two separate billing systems, and each brings its own metering. Sign in with a Claude Pro or Max subscription and Anthropic measures your usage in rolling 5-hour session windows plus a weekly cap. Authenticate with an API key instead and the Claude API counts requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM) — exceed any one and you get a 429. Same red error text in your terminal, entirely different machinery underneath. If you're still deciding how to run the tool at all, our pillar guide, What Is Claude Code?, covers both auth paths.

This ambiguity is why "limit reached despite barely using my quota" keeps filling Anthropic's issue tracker. Issue #29579 reports the error on a Max subscription showing just 16% usage, and issues #41212 and #41125 echo the same complaint. The dashboard those users checked tracks one meter; the 429 they received came from another. Most rate limit reached Claude Code threads go in circles precisely because nobody establishes which limit fired before proposing fixes.

Which limit fired? Read the signal first

Run /usage inside Claude Code before anything else. On a subscription it shows your current session percentage, your weekly percentage, and both reset times. On API billing, check the Limits page in the Claude Console and the anthropic-ratelimit-* response headers instead. Then match what you see to a row:

The diagnostic shortcut we lean on: read the reset time in the error itself. Minutes away means a per-minute API limit. A few hours means your session window. Days away means the weekly cap — and no amount of waiting out sessions will restore that one early.

Plan limits: the 5-hour window and the weekly caps

The Claude Code usage limit on subscriptions is a rolling window, not a midnight reset. Your first message starts a 5-hour clock; everything you burn inside that window counts against the session allowance, and the whole thing clears when the clock runs out. Send your first prompt at 9 AM and that session's usage ages out at 2 PM — your next message after that starts a fresh window with a fresh timer.

Stacked on top sits a weekly cap that resets on a 7-day cycle, and on Max plans a second, separate weekly cap for Opus alone. This is the pair people conflate: waiting five hours restores your session, never your week. Once the weekly meter is spent, only the rollover brings it back.

Where you sit in that table changes how often you'll see the error. On Pro, a single heavy refactor with a bloated context can exhaust a session in under an hour; we've done it. The Claude Pro plan works for an hour or two of focused daily coding, while Claude Max exists precisely for people who hit the Pro wall twice a day.

API limits: RPM, ITPM, OTPM — and the 429 that names its limit

API billing swaps usage windows for per-minute metering. Anthropic documents the whole scheme in its rate limits reference: every model carries separate RPM, ITPM, and OTPM ceilings per usage tier, exceeding any of them returns a 429 that names the limit it hit, and a retry-after header tells you exactly how long to wait. The limits use a token bucket, so capacity refills continuously rather than resetting on a fixed clock — a per-minute limit usually clears in about a minute.

For Claude Code users on API keys, input tokens per minute is the usual culprit. The agent re-sends your conversation context with every request, so a long session multiplies input volume fast. Two details soften this: cached input tokens don't count toward ITPM on current models, and each model has its own limit pool, so switching models mid-block gives you a fresh budget.

Tiers advance automatically as your usage history grows, and you can request increases from the Console's Limits page. Full per-token costs live in our Anthropic Claude API pricing breakdown.

The fixes, cheapest first

When a rate limit reached Claude Code error lands mid-task, work this list top to bottom. The first three cost nothing.

1. Wait for the reset — but only when it's short. Per-minute API limits refill in about a minute; honor the retry-after value and you lose almost nothing. A session window a few hours from reset is a coffee break or a task-switch. A weekly cap days out is not worth waiting for — move to the fixes below instead.

2. Switch to a lighter model. Type /model and drop down a class. On Max plans the Opus cap is separate, so Sonnet keeps working after Opus locks; on the API, each model's limit pool is independent. We keep Claude Opus 4.8 ($5/$25 per million tokens, and the SWE-bench Pro leader at 69.2%) for architecture and gnarly refactors, then route everything routine to cheaper models. Our Claude models guide maps which tier fits which task.

3. Reduce context. This is the highest-leverage fix nobody does. Run /compact before the context bar gets scary, /clear between unrelated tasks, and point Claude at specific files instead of letting it scan the whole repo. Anthropic's own cost management guide pushes the same habits, because every extra token in context is re-sent — and re-billed against your limits — on every single turn.

4. Upgrade the plan or tier. If you hit the wall daily, arithmetic takes over: Pro to Max 5x quintuples your allowance for $100/month, and API users can request higher limits or simply let their tier advance. A Claude rate limit error that arrives once a month is noise; one that arrives every afternoon is a sizing problem.

5. Batch and schedule the work. Split big jobs into two or three sessions a day so no single window absorbs everything. On the API, the Message Batches API processes asynchronous jobs at half price under its own separate limits — ideal for bulk refactors, test generation, or anything that doesn't need you watching.

One caution: make sure you're actually fixing a 429. A 500 is a server-side fault with a completely different playbook — our Claude Code API error 500 guide covers that one.

The quick checklist:

• Identify which limit fired: plan window or API meter
• Wait out the reset (5-hour windows are the usual)
• Switch to Sonnet or Haiku to stretch quota
• Compact context - or upgrade if it keeps happening

Claude pricing at a glance

For the full breakdown of every plan, see our how much Claude costs guide.