Claude Code Rate Limits: Subscription, API 429, or 5xx?

When Claude Code reports a limit or failed request, identify which layer handled it: a Claude.ai subscription, the Anthropic API, or a custom endpoint. Subscription limits, HTTP 429, and transient 5xx responses can look similar in a terminal, but require different actions.

Three possible layers

  • Claude subscription: usage follows the current plan and account limits. Check the message, /usage, and account settings instead of relying on old fixed numbers.
  • Anthropic API Key: requests are subject to workspace rate limits and billing tier.
  • Custom endpoint: a custom Base URL and provider key add another request log and error contract.

An API key or custom Base URL may change the route even when you previously signed in through a subscription. Run /status before assuming which account is charged.

Need to confirm whether a request reached BetterToken? Dashboard shows model, status, input/output/cache tokens, and spend without exposing the full prompt. Use the current BetterToken documentation for exact Claude Code configuration.

How the errors differ

  • Claude subscription: /status shows a Claude.ai account, and the message describes an account or usage limit. Inspect /usage and the reset condition, then wait for the stated reset.
  • Anthropic API 429: authentication uses an API key, and the response contains HTTP 429 or rate_limit_error. Inspect response headers, workspace limits, and concurrency; respect retry guidance and reduce load.
  • Custom endpoint: a custom Base URL and provider key are active, and the code can be provider-specific. Read the full provider response, then check its Dashboard, status page, and quota terms.

Not every server-side error is a personal quota:

  • 500 usually means processing failed.
  • 504 means a gateway or upstream request timed out.
  • 529 signals temporary overload.
  • 429 means a rate or usage policy rejected the request.

The response body and headers are more reliable than a shortened integration message.

Safe diagnostic sequence

1. Confirm authentication

Run /status. Record the login method and whether a custom Base URL is active. Never paste key values into a ticket or screenshot.

2. Preserve useful error data

Keep the HTTP status, error type, request time with timezone, model, Claude Code version, and the request-id header or request_id field when present. Remove authorization headers, cookies, API keys, and complete environment dumps.

3. Check the correct control plane

For subscriptions, use /usage and account settings. For Anthropic API, check workspace limits and usage in Console. For BetterToken, match the request time in Dashboard and compare status, model, token counts, and cost.

If no BetterToken record exists, the request may not have reached that endpoint. Recheck the active Base URL and environment without printing secrets.

4. Check provider status

An incident can affect requests even when your quota is healthy. Check the official status page for the endpoint that actually handled the request.

5. Retry only transient failures

For 429, follow retry guidance and lower concurrency. For 500, 504, or 529, use bounded exponential backoff with jitter. Set a maximum attempt count. Unlimited retries can increase overload and spend.

What to do next

For a subscription limit, follow the reset condition, clear unrelated context, and split broad work into smaller tasks.

For API 429, read retry-after when present, reduce parallel agent work, shorten unnecessary context, and check the active workspace tier.

For 500, 504, or 529, save request ID and time, retry with bounded backoff, and check provider status. If the problem persists, send support the safe diagnostics.

For a custom endpoint, match the request in its Dashboard, confirm that the model ID exists, and check balance and provider-specific limits. Do not assume every provider uses Anthropic's exact error format.

What to send to support

Provide timestamp, timezone, Claude Code version, active route without secret values, model, HTTP code, error type, request ID, and whether a bounded retry changed the result. Never include the full Authorization header, API key, session cookies, or complete environment dump.

Short answer

Start with /status. A subscription limit is handled in the Claude account, API 429 needs rate-limit diagnostics, and 500/504/529 usually need bounded retries plus a status check. With BetterToken, use Dashboard to confirm whether the request arrived and attach its time and safe identifier to support.

Related articles