Rate Limits in Claude Code: Subscription Limits vs API 429s

When Claude Code reports a rate limit, the first impulse is to wait or restart. The right action depends on which layer is limiting requests: a Claude.ai subscription (Pro, Max, or Team), the Anthropic API, or a third-party endpoint. The symptoms look similar, but the fixes differ.

What a rate limit means in Claude Code

Claude Code supports two fundamentally different authentication modes:

• Subscription (Pro, Max, Team, or Enterprise): sign in through Claude.ai OAuth. Claude Code and other Claude surfaces draw from the plan’s shared pool; check current windows and additional restrictions in /usage and account settings.
• API key (ANTHROPIC_API_KEY in the environment): requests go directly to api.anthropic.com. A limit may involve RPM/ITPM/OTPM, acceleration, the usage-tier spend cap, or a workspace spend cap. Classify the current case from the error body, headers, and Anthropic Console.

If ANTHROPIC_API_KEY is set, it takes precedence over the subscription. Claude Code will switch to the API key even if you signed in with a subscription—a common source of confusion.

Need to know whether the request reached a third-party endpoint? BetterToken adds another diagnostic layer: its Dashboard shows request status, model, input/output/cache tokens, and the corresponding charge. This helps distinguish a provider limit from an Anthropic API error. Use the BetterToken documentation for Base URL and API key setup, and check the configuration against your current workflow.

How to identify a subscription, Anthropic API, or other endpoint limit

Start by running /status in Claude Code. It shows the current authentication method: subscription account or API key. That determines where to investigate next.

• Pro/Max/Team subscription: /status shows a subscription, and the message mentions a session or weekly limit and reset time. The plan usage is exhausted. Wait for the reset and check /usage, plus /usage-credits if available.
• Anthropic API 429: /status shows an API key and the response contains HTTP 429 or rate_limit_error. Check retry-after, the current error body, and rate/spend limits in Anthropic Console. The same status can describe different constraints, and exact response fields depend on the endpoint and API version.
• Third-party endpoint: a custom Base URL and provider key are in use; the code and response format may differ from Anthropic. The provider’s own quota is constrained. Read the response first, then check its status page and quota terms.

Handle 500 api_error, 504 timeout_error, and 529 overloaded_error separately. These are server-side or transient errors, not proof that a subscription allowance is exhausted. Use bounded exponential backoff. Every Anthropic response contains request-id in a header, and an error also includes request_id in JSON; keep that identifier for support.

Step-by-step diagnosis without leaking an API key

Step 1. Check the authentication method

In a Claude Code session:

/status

Look at “Login method” or “Auth token.” If ANTHROPIC_API_KEY is set but you want to use a subscription, remove the variable first:

unset ANTHROPIC_API_KEY

Restart Claude Code and check /status again.

Step 2. Read the full error message

The exact text is the primary diagnostic signal:

• “Resets at [time]” → subscription limit; wait for the reset
• rate_limit_error plus a retry-after header → wait for that period and inspect Anthropic Console
• rate_limit_error without retry-after → inspect the current error body and the spend cap in Anthropic Console; do not assume it is an ordinary RPM/TPM limit
• api_error, timeout_error, or overloaded_error → transient 5xx/529 error; retry with backoff
• A provider-specific format plus a nonstandard Base URL → provider-side problem

Alongside the code, save a safe diagnostic set: time, error.type, request-id/request_id, Claude Code version, and selected endpoint. Do not include the API key, Authorization header, or .env contents.

Step 3. Check current usage

For a subscription:

/usage

The current /usage shows information available for that account and authentication mode, such as session token statistics for API users, plan usage, activity, or credits. Follow the labels and period on your own screen instead of copying fixed windows from an old tutorial.

For the API, open Anthropic Console and check the current rate limits, usage tier, and applicable spend limits. Section names and available fields can vary by account type and version.

For BetterToken, open the Dashboard and find the request by time. You can check model, status, input/output/cache tokens, and charge. The Dashboard establishes whether a request reached BetterToken, but you should still save the identifier from the response body or headers separately.

Step 4. Check official status

https://status.anthropic.com/

An incident affecting Claude Code or the API explains the problem independently of your limits.

Step 5. Check for configuration conflicts

Setting both ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL can produce unexpected behavior. Do not keep two variable sets for different authentication schemes in the same environment.

When asking for help, never include the Authorization header, x-api-key, or .env contents in logs or screenshots. The error text, HTTP code, claude --version, and /status output with key values removed are sufficient.

What to do after identifying the source

Subscription limit (Pro/Max/Team):

• Wait for the window reset shown by /usage and the error message.
• If the message concerns a model-specific limit, select an available model with /model; this does not reset overall plan usage.
• If usage credits are available, run /usage-credits and check the settings.
• Use /clear between unrelated tasks to reset context and reduce consumption on later requests.

Anthropic API 429 (rate_limit_error):

• If retry-after is present, wait for that period; retrying earlier will not help.
• If it is absent, inspect the current error body and spend limits in Anthropic Console. An enforced spend cap needs a limit change or reset, not backoff; do not bind handling to one optional response field.
• For an ordinary rate or acceleration limit, reduce concurrency and ramp traffic gradually.
• Check the current usage tier, rate limits, and spend limits instead of relying on old fixed figures.

Third-party endpoint:

• Open the provider’s status page.
• Ask the provider for its current quota and error format.
• Switch to the direct Anthropic API or another provider if necessary.

5xx / 529:

• Use bounded exponential backoff for 500, 504, and 529; the official SDK already retries some transient errors.
• Check status.anthropic.com for an incident.
• If the error persists, send support the request-id, time, and error type, but no secrets.

When to wait, change load, or contact support

• Subscription limit with a reset time: wait, switch models, or use /clear.
• API 429 with retry-after: wait for the specified period and reduce concurrency.
• API 429 without retry-after: inspect the error details and spend cap; the correct action depends on the current response and account state.
• 500 / 504 / 529: apply bounded exponential backoff, check service status, and keep the request-id.
• Third-party endpoint error: contact that provider.
• Unclear limit with an active subscription: contact claude.ai support.
• Unclear limit with an active API key: contact Anthropic Console support.

Subscription support and API support are separate teams. The Anthropic API Console team cannot fix a Pro/Max subscription limit, and vice versa.

FAQ

Why do I see “rate limit” immediately after starting a session?

Possible causes: (1) the environment contains an ANTHROPIC_API_KEY on a low tier, which takes precedence over the subscription—check /status; (2) a previous session consumed much of the rolling window, which does not reset when Claude Code restarts; (3) several devices or agent tasks use the same account, so their usage is combined.

Will switching models with /model help?

Only when the current interface explicitly offers an available model and identifies a separate model restriction. Do not treat model switching as a universal reset for plan usage; check the current /usage, error message, and plan rules.

Should I include complete logs when asking for help?

No. The full error text, HTTP code, /status output with key values removed, claude --version, time of occurrence, and the state of status.anthropic.com at that time are sufficient.

Which dynamic limits change most often?

API tier limits (RPM, ITPM, and OTPM) and subscription-window parameters can change. Get current values 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 figures from tutorials or forums; they become outdated quickly.