Claude usage limits: what to do when you hit one

What are Claude's usage limits?

Claude's usage limits come in two separate systems, and the first job is working out which one stopped you. A Claude subscription (Pro, Max, Team, or seat-based Enterprise) gives you a rolling usage allowance that is shared across models, apart from a few model-family ceilings, and shared with Claude chat, so it stops you with a message like You've hit your session limit · resets 3:45pm. Current usage-based Enterprise plans are the exception: they have no included allowance, and all usage is billed at API rates from the first token. The Claude API measures something else: how fast you send requests and tokens, counted per minute. It stops you with an HTTP 429 error of type rate_limit_error, usually with a retry-after header saying how many seconds to wait.

The fixes have nothing in common. A subscription limit is about how much you used inside a window, so you wait for the reset, buy more usage, or spend a free limit reset if your plan has been offered one. An API rate limit is about your speed right now, and it clears in seconds once you slow down.

Plan allowances and rate-limit tier numbers change often, and a wrong number is worse than none, so none are printed here. Read your own with the commands further down.

Which limit did you hit? Read the exact message

Claude Code names the system in the text it prints. Match yours before you change anything.

• You've hit your session limit · resets 3:45pm is a subscription limit. Your plan's rolling allowance for this window is spent.
• You've hit your weekly limit · resets Mon 12:00am is the same system on the longer window.
• You've hit your Opus limit · resets 3:45pm is a subscription limit that applies only to Opus requests. Switching to a model outside the Opus family keeps you working.
• You've hit your Sonnet limit · resets 3:45pm is the same kind of model-family limit, for Sonnet requests only. Switching to a model outside the Sonnet family keeps you working.
• A message that starts Fable limit reached means you have used the share of your weekly allowance that Fable models may take. Continuing on Fable bills usage credits, so Claude Code asks you to confirm first. Pick another model with /model to stay inside your plan.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. is an API rate limit. You hit the limit configured for your API key, or for your Amazon Bedrock or Google Cloud project. Which of those applies depends on how the client authenticates, since a Bedrock or Vertex client is metered against your cloud project's quota rather than an Anthropic organization.
• API Error: Server is temporarily limiting requests (not your usage limit) is a short-lived throttle unrelated to your plan quota. Claude Code retries it automatically with backoff before it shows you that line.

Subscription limits: session, weekly, and the Opus window

A Pro, Max, Team or seat-based Enterprise plan includes a rolling usage allowance. When it is exhausted, Claude Code blocks further requests until the reset time shown in the message. Two properties of that allowance cause most of the confusion.

• It is shared with Claude chat. Work you do on claude.ai draws from the same allowance as work in the terminal, so a heavy afternoon in chat shortens your coding evening. Every surface you sign in to with that account draws on the same pool, so on Linux the beta desktop app and the Claude Code CLI spend one allowance between them, not one each.
• It is shared across models. Session and weekly limits are one pool for every model. The exceptions are model-family ceilings inside that pool: the Opus and Sonnet limits, and on Max and Premium seats a Fable allocation of up to 50% of your weekly limits. On Pro and Standard seats, Fable is not included in plan limits at all and bills to usage credits from the first request.

On Claude for Teams and seat-based Enterprise the documented shape is a per-seat allowance that resets on a rolling five-hour window and a weekly window, is shared with Claude chat and Cowork, and is sized by the seat tier (Standard or Premium). Current usage-based Enterprise plans work differently: there is no included allowance to run out of, usage is billed at API rates, and the ceiling is whatever spend limits admins set at the organization level and for individual users. On a sales-assisted plan, usage stopped by a spend limit resumes at the start of the next billing period unless an owner raises the limit first. On a self-serve plan, usage also stops when the prepaid credit balance runs out, until an owner buys more. On Pro and Max, the reset time printed in the message and your own /usage bars are the reliable numbers, not a figure copied from a blog post. If you are still picking a tier, which Claude plan you need compares what each one gates.

Why switching model with /model does not restore a session or weekly limit

This is the most common wrong move, and the documentation is blunt about it: session and weekly limits are shared across all models, so switching models doesn't restore access. Picking a smaller model after your session window is spent changes which model would answer. It does not change how much allowance is left, because the session and weekly allowance is not held per model, so the switch has nothing to release.

The exceptions are the model-family ceilings. If the message reads You've hit your Opus limit or You've hit your Sonnet limit, then /model is the correct fix. Switch to a model outside that family and keep working, because only that family's requests were blocked. The Fable limit on Max and Premium seats works the same way: switch to another model to keep working within your plan, or carry on with Fable on usage credits. Fable draws on the shared weekly pool faster than other models, though, so a switch after the Fable limit never takes you past your overall weekly limit.

Treating the limit as a bug is the second wrong move. Reinstalling or re-authenticating changes nothing. The allowance comes back when the window resets, when you spend a free limit reset, or when you buy usage credits.

What to do when you hit a subscription limit

1. Read the reset time. A session window is short. A weekly window is not something you wait out at your desk. On Claude Code v2.1.234 or later, /rate-limit-options can wait for the reset and continue the interrupted task automatically.
2. If it is the Opus, Sonnet or Fable limit, run /model and pick a model outside that family.
3. Run /usage to see your plan limits, your bars, and when they reset. /cost is an alias for the same screen.
4. Check Settings > Usage on claude.ai or in Claude Desktop for a Resets section. Eligible plans are occasionally offered a free limit reset, and clicking "Reset for free" sets your five-hour session limit or your weekly limit, whichever the offer covers, back to full right away. The button is not available in Claude Code in a terminal or IDE, or on Claude Mobile, and each offer expires.
5. Run /usage-credits to keep working past the ceiling. On Pro and Max it opens your billing settings. On Team and Enterprise it opens your organization's usage settings, or sends a request to your admins if you have no billing access.
6. If you hit the same wall every week, the plan is the wrong size for the way you work, and the routes out of a usage limit are worth weighing once rather than at every reset.

/usage-credits needs a claude.ai subscription signed in through /login. It is unavailable with API key authentication, because an API key has no plan allowance to extend.

Usage credits have one side effect worth knowing first. By default, Claude Code gives your main conversation a one-hour prompt cache while you are within a subscription's included usage, and drops it to five minutes once you are drawing on credits, so more turns start cold and Claude Code token usage climbs for the same work. Subagents sit outside that main-conversation bucket, so they get five minutes even within plan usage. Choosing the TTL yourself, with the promptCacheTtl setting or CLAUDE_CODE_PROMPT_CACHE_TTL on Claude Code v2.1.242 or later, keeps the one-hour lifetime while you draw on credits.

The messages that look like usage limits and are not

Four Claude Code errors get reported as usage limits and are none of them.

• A context or auto-compact warning is not a usage limit. /context prints a line such as Context exceeds the 200k-token limit by 94k tokens, followed by the command that frees space, once the conversation has grown past the model's context window. Compacting summarizes older history to free space, but it is not free: /compact reads the conversation it summarizes, so compacting a large context is itself a large request against your plan. When you want a fresh start instead of continuity, /clear costs nothing.
• Prompt is too long · automatic compaction failed: <the underlying error> means automatic compaction itself failed, on the error it names. /compact keeps failing on that same error until you resolve it.
• Credit balance is too low means your Console organization has run out of prepaid credits, or Claude Code is sending a subscriber's requests through a Console API key; /status shows which credential is active. Add credits at platform.claude.com/settings/billing, which also offers auto-reload.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context is an entitlement check, not an exhausted quota. If you selected a [1m] variant of Opus 4.6 or Sonnet 4.6, pick the variant without the [1m] suffix, or set CLAUDE_CODE_DISABLE_1M_CONTEXT=1. If it appears mid-conversation because the context grew past 200K tokens, Claude Code compacts back under the standard limit on its own. Sonnet 5 and later, Opus 4.7 and later, Haiku 5.5 and the Fable models run with a native 1M window and have no suffix to remove; that variable is what holds them to 200K.

One more comes from the API. A 413 request_too_large is a size limit on a single request, not a rate limit.

API rate limits: what the 429 is actually counting

The Messages API measures three things, separately for each model class.

• requests per minute (RPM)
• input tokens per minute (ITPM)
• output tokens per minute (OTPM)

Your organization also has a spend limit, which is a different thing: a maximum monthly cost for API usage. Once you reach your tier's spend cap, API usage pauses until the next month unless you request a higher limit. It arrives as a 429 rate_limit_error too, but with no retry-after header and with enforced_spend_limit_reached in error.details.error_code. No retry loop solves that. A lower spend limit you set yourself in the Console shows up differently again: requests return HTTP 400 invalid_request_error with a message starting You have reached your specified API usage limits, and raising or removing the limit restores access.

Four mechanics decide when the 429 arrives.

• Limits are per model class. They apply separately to each model, so you can use different models up to their respective limits at the same time. Some families share a bucket: the Opus rate limit is a total across Claude Opus 4.8, Opus 4.7, Opus 4.6 and Opus 4.5, while Claude Sonnet 5 has its own.
• Capacity refills continuously. The API uses a token bucket algorithm, so capacity replenishes continuously instead of resetting at a fixed moment. A limit of 60 requests per minute may be enforced as one request per second, so 60 requests fired at once still fail.
• Only uncached input counts toward ITPM on most models. input_tokens and cache_creation_input_tokens count. cache_read_input_tokens does not on most Claude models, with Claude Haiku 3.5 the documented exception. Caching therefore buys rate-limit headroom as well as a discount. On the output side, a high max_tokens does not count against OTPM, because OTPM counts only the tokens actually produced.
• Limits live at the organization level. A workspace can be given a lower limit, and organization-wide limits always apply even if workspace limits add up to more. A limit you have not overridden on a workspace is inherited from the organization, not left unlimited.

Tiers named Start, Build, Scale and Custom set the actual numbers, assigned automatically from your usage history and account standing. New organizations and those with little usage history may start in the Evaluation tier, below the standard published limits, so a first 429 can arrive earlier than a table predicts. A sharp increase in usage triggers acceleration limits, which return 429 while you are still inside your tier, so ramp traffic up gradually. Every published figure is a ceiling: documented limits are maximum allowed usage, not guaranteed minimums. To ask for more, use "Request tier increase" on the Rate limits page in the Claude Console.

Reading a 429: retry-after, the headers, and SDK retries

Every API error returns the same envelope: a nested error object carrying the type and the message, plus a top-level request_id.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

The headers carry the rest.

• retry-after is the number of seconds to wait until you can retry the request. Earlier retries will fail. Not every 429 carries it, and the spend-cap 429 never does.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining and anthropic-ratelimit-requests-reset describe your request budget.
• anthropic-ratelimit-input-tokens-* and anthropic-ratelimit-output-tokens-* do the same for ITPM and OTPM, with the same limit, remaining and reset suffixes.
• anthropic-ratelimit-tokens-* displays the values for the most restrictive limit currently in effect.

Reset headers are RFC 3339 timestamps. Remaining token headers are rounded to the nearest thousand, so read them as a gauge. Fast mode has its own pool and its own anthropic-fast-* headers. Read all of them from any successful call:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

Every response also carries a unique request-id header, such as req_018EeWyXxfu5pfWkrYcMdjWG. It appears as request_id in error bodies and as _request_id on Python and TypeScript SDK responses. Quote it when you contact support.

Check whether you need a backoff loop at all before you write one. The official SDKs automatically retry transient failures, including connection errors, rate limits and 5xx server errors, with exponential backoff, twice by default, honoring the retry-after header when it is present. Each client accepts a maximum-retries option to change or disable that behavior.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error is not your fault

A 429 says you went too fast. A 529 overloaded_error says the API is temporarily overloaded, and it can occur when the API experiences high traffic across all users. Nothing about your key or your code caused it. Retry with exponential backoff, which the SDKs already do for 5xx responses, and check status.claude.com if it does not clear. A 500 api_error is an internal error you retry the same way, and neither one is a rate limit.

Read your own limits instead of a table

On a subscription, /usage is the screen that matters. It shows your plan usage bars and a breakdown of what consumed them, and d or w switches between the last 24 hours and the last 7 days. Two caveats. The Session block shows API token usage and is meant for API users, so subscribers can ignore its dollar figure. The numbers come from local session history on that machine, so usage from another device or from claude.ai is missing.

On the API side, the Usage page in the Claude Console draws two charts, "Rate Limit - Input Tokens" and "Rate Limit - Output Tokens". The input chart plots the hourly maximum of uncached input tokens per minute against your current ITPM limit, with your cache rate beside it, so you watch a limit approach instead of meeting it in production.

To read your configured limits programmatically:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

It needs Admin API credentials: an Admin API key, an OAuth token with the org:admin scope, or a personal or service account key that is not scoped to a workspace. Workspace API keys do not work. GET /v1/organizations/workspaces/{workspace_id}/rate_limits does the same per workspace. Both are read-only: to change a limit, use the Rate limits page in the Console.

Using less, so you meet fewer limits

Both systems meter the same thing underneath, so these levers work on either.

• Spend fewer tokens per turn. Continuous stints keep the cache warm, and /clear between unrelated tasks costs nothing. Claude Code token usage covers those levers in full.
• Lower the effort. The levels are low, medium, high, xhigh and max. The /effort menu also offers ultracode, which raises spend rather than lowering it. Deep reasoning on a mechanical rename buys nothing.
• Cut concurrency after a 429. Lower CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY and avoid many parallel subagents. Run /status too: a stray ANTHROPIC_API_KEY routes requests through a low-tier key instead of your subscription.
• Move non-interactive work to the Message Batches API. It runs large volumes asynchronously at a 50% discount on input and output tokens, under its own rate limits, so a nightly job stops competing with your session.

Work that pours data into context feels this hardest: if you are analyzing stocks and options against live market data, pulling the narrow slice each question needs costs a fraction of pasting whole tables of quotes and chains. Bursty work driven by a program rather than a person belongs on an API key from the start. Moving there changes how you pay as well as how you are metered, since the Claude API has no free tier. Max and Team plans do include monthly API credits for running your own apps and agents once you link a Console organization. Those credits do not cover Claude Code and do not change your plan's usage limits. Your first Claude API app on a VPS covers key handling and retries, and a long agent run survives a dropped connection when you keep Claude Code running on a VPS inside tmux.

FAQ

Why does switching models not fix my Claude usage limit?

Because session and weekly limits are shared across all models. That allowance belongs to the plan, not to a model, so /model changes which model would answer and not how much allowance is left. The exceptions are the model-family limits: You've hit your Opus limit and You've hit your Sonnet limit apply only to that family, and the Fable limit on Max and Premium seats caps Fable alone. There, switching model is the documented fix.

What does the 429 rate_limit_error mean, and how long should I wait?

It means your account hit a rate limit for that model class: requests per minute, input tokens per minute, or output tokens per minute. The response usually carries a retry-after header with the seconds to wait, and earlier retries fail. The official SDKs already retry rate limits and 5xx errors with exponential backoff, twice by default, honoring that header when it is present. A 429 that arrives while you are still inside your tier's limits points at an acceleration limit from a sudden ramp. A 429 with enforced_spend_limit_reached in error.details.error_code, which never carries a retry-after header, is the monthly spend cap, and waiting minutes will not clear it.

How do I see my Claude usage limits and when they reset?

In Claude Code, run /usage for your plan bars, reset times and a usage breakdown; /cost is an alias, and d or w switches between the last 24 hours and the last 7 days. Those figures come from local session history, so they miss usage from other devices and from claude.ai. On the API, the Console charts your rate limits, and GET /v1/organizations/rate_limits returns your configured limits with Admin API credentials, such as an Admin API key.

Can I keep working after hitting my Claude plan limit?

Sometimes. Run /usage-credits to buy usage past the ceiling on Pro and Max, or to request it from an admin on Team and Enterprise; it needs a claude.ai login through /login and is unavailable with API key authentication. Otherwise wait for the reset time, use a free limit reset if Settings > Usage on claude.ai or Claude Desktop offers one, switch model if it was the Opus, Sonnet or Fable limit, or move the work to an API key, which meters per minute rather than per window.