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. Limits are the RPM, ITPM, and OTPM for your workspace tier in 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, ANTHROPIC_API_KEY exists in the environment, and the response contains HTTP 429 or rate_limit_error. The selected tier's RPM, ITPM, or OTPM is constrained. Check retry-after first and reduce concurrency.
• 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 → API 429; inspect Anthropic Console
• 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

This shows Pro/Max usage bars: what remains before the five-hour window resets and before the weekly ceiling. Switching models with /model does not restore compute hours already consumed; the allowance is shared across models.

For the API, open Anthropic Console → Settings → Limits. It shows the tier, current RPM/ITPM/OTPM limits, and usage.

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):

• Read retry-after in the response and wait for that period.
• Reduce concurrency: parallel agent tasks consume RPM, ITPM, and OTPM faster.
• Check the current tier and limits in Anthropic Console → Settings → Limits instead of relying on old fixed figures.
• For long-term growth, contact Anthropic through Console about raising the limits.

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.
• Frequent API 429 without retry-after: check the tier and request a higher limit if needed.
• 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?

Partly for subscriptions. “You've hit your Opus limit” means the Opus allowance is exhausted, and switching to Sonnet may let you continue in the same session. The shared weekly and five-hour compute budget is not restored by switching models.

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.

---

Originally published on the BetterToken blog.

BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.