Claude rate limit error: which limit did you actually hit?

Two completely different systems produce the words "rate limit", and the fix depends entirely on which one you are in. If you are calling the API, a rate_limit_error with HTTP 429 means you exceeded a per-minute quota and you should back off and retry. If you are on a Pro or Max subscription, you almost certainly hit a usage limit instead, which is a five-hour or weekly window rather than a per-minute quota, and no amount of retrying will clear it.

Two systems, one confusing word

The API has rate limits. They are enforced per organization and measured in requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM), separately for each model. Your ceilings are set by your organization's usage tier, and Anthropic uses a token bucket algorithm, so capacity replenishes continuously rather than resetting on the hour. Exceed one and you get a 429 whose body carries "type": "rate_limit_error", plus a retry-after header telling you how many seconds to wait.

Subscriptions have usage limits. Pro, Max, Team, and Enterprise plans meter a rolling five-hour session window plus weekly caps, one across all models and a separate one for Opus. There is no per-minute quota to tune, no retry-after, and no requests-per-second figure that matters. Access pauses until that window rolls off.

The two never mix, because they belong to separate products on separate billing. A subscription has no usage tier and no RPM. An API key has no five-hour window. If someone tells you to "add exponential backoff" for a session limit, they have diagnosed the wrong system.

How to tell which one you hit

Start with the credential, not the message. Are you calling the Claude API with a key, or using claude.ai, the desktop app, or Claude Code signed in with a subscription? That answers it most of the time. In Claude Code, run /status: a Login method row means subscription, an API key row means metered. Run /usage: plan usage bars mean subscription; only a session cost figure means API billing. The full breakdown is in Claude Code: subscription or API billing.

Then read what you were actually handed:

• An API rate limit is HTTP 429, error type rate_limit_error, with a retry-after header and a message naming which limit was exceeded. Responses also carry anthropic-ratelimit-requests-remaining, anthropic-ratelimit-input-tokens-remaining, and anthropic-ratelimit-output-tokens-remaining with matching -limit and -reset headers, so you can see which ceiling you are pressed against.
• A spend cap is the confusing one: it also returns 429 with rate_limit_error, but it has no retry-after header, and on the Messages API error.details.error_code is enforced_spend_limit_reached. Retrying cannot help; usage is paused until the next calendar month or until you move to a higher tier. Use that error code to tell the two apart in your handler.
• A spend limit you set yourself returns HTTP 400 with type invalid_request_error, and the message begins "You have reached your specified API usage limits".
• A subscription usage limit says so in words: "You've hit your session limit", "You've hit your weekly limit", "You've hit your Opus limit", or "You've hit your Sonnet limit", and it tells you when the window resets.

Fixing it on the API

A 429 with a retry-after header is an ordinary, expected part of running at volume. In rough order of leverage:

• Back off and retry, honoring retry-after. Retrying earlier than the header says will fail. Exponential backoff with jitter on top of that value handles the common case; the official SDKs already retry for you.
• Cache your stable prefix. The biggest structural win, because on most models cache_read_input_tokens do not count toward your ITPM limit at all. Cache system instructions, tool definitions, long documents, and conversation history, and effective throughput rises without your ceiling changing. Anthropic's own example: with a 2,000,000 ITPM limit and an 80% cache hit rate you can effectively process 10,000,000 input tokens a minute.
• Spread the load. A per-minute limit can bite in a sub-minute burst, since a 60 RPM allowance may be enforced as one request per second. Cap concurrency and pace your queue.
• Ramp gradually. A sharp jump in traffic can trip acceleration limits even below your posted ceiling. Grow into new volume over hours rather than minutes.
• Use the Batch API for anything asynchronous. It has its own separate rate limits, and batched work costs 50% less on both input and output. Classification, enrichment, evals, and bulk summarization belong here.
• Move up a usage tier. Organizations are placed on a tier automatically from usage history and move up over time; new organizations may start in the Evaluation tier, below the standard published limits. If you need more now, use Request rate limit increase on the Rate limits page in the Claude Console.
• Split models and workspaces. Limits apply separately per model, so routing routine work to a smaller model relieves pressure on the big one. And if Claude Code shares an organization with production traffic, cap its workspace.

Fixing it on a subscription

None of the above applies. There is no backoff strategy for a window; there is a clock. Your options:

• Read the reset time and wait. /usage in Claude Code, or Settings > Usage in the apps, shows the exact time in your local timezone. A session limit is hours; a weekly limit is days. See how to check your Claude usage.
• Switch model, if the message named one. "You've hit your Opus limit" or "You've hit your Sonnet limit" is model-specific: switching to a model outside that family with /model keeps you working immediately. A plain session or weekly limit is shared across all models, so switching will not help.
• Let Claude Code wait for you. Recent versions can wait for the reset and then continue the interrupted task automatically; /rate-limit-options is where you choose that behavior.
• Turn on usage credits. On paid plans you can keep working past the included limit, billed at standard API pricing rates, with an optional monthly spend cap. Enable it in Settings > Usage, or run /usage-credits in Claude Code.
• Fix the burn rate. If you land here weekly, the cause is usually habit rather than plan size: long sessions never cleared, or Opus left as the default. Reducing Claude Code token usage often buys back more room than an upgrade would. If it is genuinely capacity, compare tiers in Max 5x vs 20x.

What Claude Code shows in each case

Claude Code sits on both systems, which is exactly why the confusion concentrates there. It distinguishes them, if you know what you are reading.

A transport-level 429 surfaces as Request rejected (429) or Server is temporarily limiting requests. Claude Code retries these automatically within its retry budget, so a brief throttle usually resolves itself while you watch. If it persists, you are pressed against a real per-minute ceiling and the fixes above apply.

A spend limit or exhausted usage credits also arrives as a 429, but Claude Code deliberately fails at once rather than retrying, because retrying a spend cap can never succeed. Look for spend limit reached or Credit balance is too low.

A subscription usage limit is stated plainly: "You've hit your session limit" or "You've hit your weekly limit", with the reset time. There is no retry involved and nothing is wrong with your account.

One more error swept into the same search and neither of these: "Claude reached its tool-use limit for this turn" is a structural cap on how many tool calls one response may make. It resets on the next turn, and your plan is untouched.

If you keep hitting limits, look at what is not being used

A closing observation for the subscription case. People who hit usage limits are running genuinely heavy agentic work, and they are usually the same people whose weekly bars finish well short of full, because one intense afternoon can exhaust a five-hour window while the weekly ceiling is barely touched. Subscription capacity is a ceiling, not a balance: whatever is left when a window resets is gone.

Tokens for Good puts that recurring surplus to work. Your Claude Code claims a queued nonprofit, researches its real-world impact against a fixed methodology with citations, and submits a structured report, then stops. Every organization is researched twice by independent contributors, then validated, consolidated, scored deterministically, and human-reviewed before it reaches the public directory. It runs on the subscription you already pay for with no separate API cost, and it can run on a schedule in the background, so it fills the windows your own work never reaches. "Tokens" here means AI model tokens, not crypto: no coin, no wallet, no blockchain. See how the research works, read what Tokens for Good is, or set it up from the docs.

Frequently asked questions