When Claude Code shows a rate limit message, the first instinct is to wait or restart. But the right action depends on which layer is limiting the request: a Claude.ai subscription such as Pro, Max or Team, the Anthropic API, or a third-party endpoint. These cases can look similar, but they need different checks.
What rate limit means in Claude Code
Claude Code can work with two fundamentally different authentication modes:
- Subscription (Pro, Max, Team, Enterprise): login through
claude loginor claude.ai OAuth. Requests go through the claude.ai gateway. Limits are based on a rolling 5-hour window and a weekly cap shared across Claude Code, Claude chat and Cowork. - API Key (
ANTHROPIC_API_KEYin environment variables): requests go directly toapi.anthropic.com. Limits are RPM, ITPM and OTPM according to the tier of your Anthropic Console workspace.
If ANTHROPIC_API_KEY is set in the environment, it takes priority over the subscription. Claude Code will switch to the API key even if you are logged in with a paid subscription. This is one of the most common sources of confusion.
If you use a custom API endpoint, for example BetterToken as an intermediary provider for Claude Code, there is one more diagnostic layer: you need to see whether the request reached the provider and where it failed. In BetterToken Dashboard you can check request status, model, input/output/cache tokens and the corresponding spend. That helps separate your provider limit from an Anthropic API error. To configure Base URL and API Key, open the BetterToken documentation and compare it with your current workflow.
How to tell: subscription, Anthropic API or another endpoint
The first step is always to run /status inside Claude Code. It shows the current authentication method: subscription account or API Key. That decides which troubleshooting path to follow.
| Signal | Subscription (Pro/Max/Team) | Anthropic API 429 | Third-party endpoint |
|---|---|---|---|
| Error text | “You've hit your session limit”, “You've hit your weekly limit”, “Resets at [time]” | “API Error: Request rejected (429)”, rate_limit_error in JSON |
429 or another provider-specific code; format may differ from Anthropic |
| Authentication | OAuth / login (claude.ai), /status shows subscription |
ANTHROPIC_API_KEY in env, /status shows API Key |
Custom Base URL (ANTHROPIC_BASE_URL) and the provider's own API Key |
| What is limited | Compute hours: rolling 5-hour window plus weekly cap | RPM, ITPM, OTPM by tier | The provider's quota |
| First action | Wait for reset, run /usage, and if available /usage-credits |
Check retry-after, reduce concurrency |
Check the provider status page and quota |
A separate case is 529 overloaded_error or “Server is temporarily limiting requests”. That is not your personal limit. It means Anthropic is signalling server overload. The right action is to wait, not to flood the service with retries.
Step-by-step diagnosis without leaking API keys
Step 1. Check the authentication method
Inside Claude Code:
/status
Look at the “Login method” or “Auth token” field. If ANTHROPIC_API_KEY is present in your environment and you want to work through the subscription, remove the variable first:
unset ANTHROPIC_API_KEY
Then restart and check /status again.
Step 2. Read the full error text
The exact error text is the main diagnostic signal:
- “Resets at [time]” means a subscription limit, so wait for the reset
rate_limit_errorplus aretry-afterheader means API 429, so check Anthropic Console- A provider-specific format plus a non-standard Base URL means the issue is on the provider layer
Step 3. Check current usage
For a subscription:
/usage
This shows Pro/Max usage bars: how much remains before the 5-hour window and weekly cap reset. Switching models with /model does not restore already spent compute hours; the budget is shared across models.
For API usage, open Anthropic Console -> Settings -> Limits. There you can see the tier, current RPM/ITPM/OTPM limits and usage.
Step 4. Check official status
https://status.anthropic.com/
If the status page has an incident for Claude Code or the API, that can explain the problem regardless of your own limits.
Step 5. Check configuration conflicts
A setup where both ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL are present can be hard to reason about. Two sets of variables for different authentication paths should not exist in the same environment at the same time.
When asking for help with the error, never include the value of the Authorization header, x-api-key, or the contents of a .env file in logs or screenshots. The error text, HTTP code, claude --version, and /status output without key values are enough.
What to do after finding the source of the limit
Subscription limit (Pro/Max/Team):
- Wait for the reset window shown by
/usageor the error text. - Switch to Sonnet or Haiku with
/model; they usually consume compute budget more slowly than Opus. - If usage credits are available, run
/usage-creditsand check the settings. - Use
/clearbetween unrelated tasks to reset context and reduce spend on the next request.
Anthropic API 429 (rate_limit_error):
- Read the
retry-aftervalue in the response and wait for that period. - Reduce concurrency. Agentic tasks with several subtasks can hit Tier 1 limits quickly.
- Check your tier in Anthropic Console -> Settings -> Limits. Tier 1 has strict RPM and ITPM limits, and one large-context agent request can exhaust them.
- For long-term scaling, contact Anthropic about increasing limits through Console.
Third-party endpoint:
- Open the provider's status page.
- Ask the provider about the current quota and error format.
- If needed, switch to direct Anthropic API or another provider.
Overloaded / 529:
- Wait. This is Anthropic server overload, not your personal limit.
- Check
status.anthropic.comfor an incident. - Do not try to work around it with frequent retries; that only increases load.
When to wait, reduce load or contact support
| Situation | Recommendation |
|---|---|
| Subscription limit with a reset time | Wait, switch model, use /clear |
API 429 with retry-after |
Wait for the specified period, reduce concurrency |
API 429 without retry-after, repeated often |
Check tier, consider requesting higher limits |
| 529 Overloaded | Wait and watch status.anthropic.com |
| Error from a third-party endpoint | Contact the provider |
| Limit unclear, subscription active and paid | Contact claude.ai support |
| Limit unclear, API Key active | Contact Anthropic Console support |
Subscription support and API support are separate paths. A Pro/Max subscription limit will not be solved by the Anthropic API Console team, and vice versa.
FAQ
Why do I see “rate limit” even though I just started the session?
Possible reasons: (1) ANTHROPIC_API_KEY is set in the environment and has priority over your subscription. Check /status. (2) A previous session already consumed a large part of the rolling window; restarting Claude Code does not reset it. (3) Multiple devices or agentic tasks using the same account add up.
Does changing the model with /model help?
For subscriptions, partly. “You've hit your Opus limit” means the Opus limit is exhausted, and switching to Sonnet can let you continue in the same session. But the shared weekly and 5-hour compute budget is still shared; switching models does not restore it.
Should I include full logs when asking for help?
No. For diagnosis, provide the full error text, HTTP code, /status output without key values, claude --version, the time of the error, and the state of status.anthropic.com at that moment.
Which dynamic limits change most often?
API tier limits (RPM, ITPM, OTPM) and subscription window details can change. Current values should come only from official pages:
- Costs and usage: code.claude.com/docs/en/costs
- API errors and rate limits: platform.claude.com/docs/en/api/errors
- Service status: status.anthropic.com
Do not trust numbers copied from tutorials or forums; they become stale quickly.