Rate limit reached during a coding session
Developers often cannot tell whether the limit is from the account, workspace, model route, or gateway.
Check account limits first, then lower concurrency and retry with a smaller context.Claude Code API troubleshooting
Fix Claude Code rate limits, 500s, 529 overloads, and API key confusion
A single runbook for the errors developers keep hitting in Claude Code: API key setup, Pro or Max versus API billing, Messages-compatible endpoints, rate limits, server errors, and overloaded routes.
claude-code-diagnostics
$ claude-code run --model claude-sonnetAPI Error: rate limit reachedstatus=429 route=messages tokens=128k retries=3next: reduce concurrency, verify key, retry with backoff
4 error families1 runbook0 thin pages
Community signals
What developers keep asking in public threads
Instead of copying community screenshots into the site, these cards turn the recurring Reddit and X patterns into stable, source-safe troubleshooting prompts.
API key versus Pro or Max subscription
A common confusion is assuming a Claude subscription automatically includes API credits.
Treat Claude subscription access and API billing as separate unless the provider page says otherwise.500 or 529 during agent loops
Long agent runs can hide whether the failure is provider overload, a gateway route issue, or one bad retry loop.
Log status code, request id, route, model, token size, and retry count before changing code.Error map
Start from the status code, not the rumor
The fastest fix is to separate key problems, quota problems, server errors, and overload.
429
Rate limit reached
Your account, workspace, model, or route is sending more requests or tokens than allowed.
- Reduce parallel agent runs
- Trim long context
- Retry with backoff
- Check current quota and model limits
500
API server error
The provider or route returned a server-side failure. One retry may work; repeated failures need routing evidence.
- Capture request id
- Retry once
- Switch route if repeated
- Avoid rewriting prompts as the first response
529
Overloaded
The upstream service is under heavy load. This is usually not fixed by changing the API key.
- Back off
- Use fallback model
- Lower request size
- Check support/status channels
401/403
API key or permission issue
Claude Code is not using the key you expect, or the key lacks access to the requested model or endpoint.
- Confirm ANTHROPIC_API_KEY
- Check base URL
- Check model access
- Separate subscription login from API billing
Runbook
Before you change code, collect these facts
- Write down the exact error text, HTTP status, model, endpoint, and time.
- Confirm whether Claude Code is using a direct Anthropic key or a compatible gateway base URL.
- Check API key billing and quota separately from Claude Pro or Max subscription status.
- If the error is 429, reduce concurrency and context size before switching providers.
- If the error is 500 or 529, retry once with backoff, then compare another route or fallback model.
- If using a gateway, verify the Messages-compatible endpoint, model route, cache behavior, and support page before blaming Claude Code itself.
Pro or Max is not the same thing as API billing
If a developer says Claude Code has an API key problem, check the active key, base URL, and billing source. Do not assume a subscription plan and API credits are the same account bucket.
Get API accessUsing a gateway? Verify the Messages endpoint
Claude Code-style clients usually need a Messages-compatible endpoint, a valid API key, and a model route that supports the requested workload.
Check docsFAQ
Claude Code API errors
Why does Claude Code say API Error: rate limit reached?
The request volume, token volume, or model route has crossed a limit. Check the active API key, workspace, model route, context size, and parallel agent runs before changing prompts.
Does Claude Pro or Max include an API key for Claude Code?
Treat Claude subscription access and API billing as separate unless the official account or provider page says they are linked. Claude Code can use different authentication paths, so verify the active key and billing source.
What should I do for Claude Code API Error 500?
Capture the request id, retry once with backoff, and check whether the same model route fails repeatedly. If it repeats, switch route or contact support with the exact time, model, and request id.
What does 529 overloaded mean for Claude Code?
529 means the upstream service is overloaded. Wait, back off, reduce request size, or use a fallback route. Replacing the API key usually does not solve overload by itself.
Sources
Where to verify the current rules
Use official docs for final limits and error semantics. Use community threads as demand signals, not as the source of truth.