Rate limit reached during a coding session
Your account, workspace, model, or route is sending more requests or tokens than allowed.
Reduce parallel agent runs · Trim long contextClaude Code API troubleshooting
Fix Claude Code rate limits, 500s, 529 overloads, and API key confusion
A single runbook for 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
Recurring Reddit and X patterns are turned into stable, source-safe troubleshooting prompts.
API key versus Pro or Max subscription
Check the active key, base URL, and billing source. Do not assume a subscription plan and API credits use the same account balance.
Check model access · Separate subscription login from API billing500 or 529 during agent loops
The provider or route returned a server-side failure. One retry may work; repeated failures need routing evidence. The upstream service is under heavy load. This is usually not fixed by changing the API key.
Capture request id · Back offError 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
Check the active key, base URL, and billing source. Do not assume a subscription plan and API credits use the same account balance.
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 the rate limit was 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
Does Claude Pro or Max include an API key?
Check the active key, base URL, and billing source. Do not assume a subscription plan and API credits use the same account balance.
What should I do for API Error 500?
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
What does 529 overloaded mean?
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
Sources
Where to verify the current rules
Use official docs for limits and error semantics. Community threads show demand, not the source of truth.