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 Enterprise) gives you a rolling usage allowance that is shared across models and shared with Claude chat, so it stops you with a message like You've hit your session limit · resets 3:45pm. 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 and 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 or buy more usage. 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. This is the one case where switching model helps.
• 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.
• 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 subscription 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.
• It is shared across models. Session and weekly limits carry no per-model budget, with the single exception of the Opus limit.

On Claude for Teams and 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). 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 access

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 allowance was never held per model, so the switch has nothing to release.

The exception is the Opus limit, a genuinely model-specific ceiling. If the message reads You've hit your Opus limit, then /model is the correct fix. Switch to another model and keep working, because only Opus requests were blocked.

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, 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.
2. If it is the Opus limit, run /model and pick another model.
3. Run /usage to see your plan limits, your bars, and when they reset. /cost is an alias for the same screen.
4. 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.
5. If you hit the same wall every week, the plan is the wrong size for the way you work.

/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. The prompt cache lifetime is an hour on a subscription and drops to five minutes once you are drawing on credits, so more turns start cold and Claude Code token usage climbs for the same work.

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 — run /compact or /clear to continue. once the conversation has grown past the model's context window. Older history is summarized to free space, and your plan allowance is untouched.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. means /compact itself failed, because there is not enough free context left to hold the summary it would produce.
• Credit balance is too low means your Console organization has run out of prepaid credits. 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, or /model to switch to standard context is an entitlement check, not an exhausted quota. Pick the model variant without the [1m] suffix, or set CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

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. No retry loop solves that.

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 may start 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 the "Request rate limit increase" control on the 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.
• 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 an Admin API key, and GET /v1/organizations/workspaces/{workspace_id}/rate_limits does the same per workspace. Both are read-only: to change a limit, use the Limits tab 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.

Bursty work driven by a program rather than a person belongs on an API key from the start. 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. The allowance belongs to the plan, not to a model, so /model changes which model would answer and not how much allowance is left. The one exception is You've hit your Opus limit, which applies only to Opus requests. 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 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. A 429 that arrives while you are still inside your tier's limits points at an acceleration limit from a sudden ramp.

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 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, switch model if it was the Opus limit, or move the work to an API key, which meters per minute rather than per window.