Fix Claude Code rate limits, 500s, 529 overloads, and API key confusion
A troubleshooting guide for API key setup, Pro or Max versus API billing, Messages-compatible endpoints, rate limits, server errors, and overloaded routes.
Questions to ask when diagnosing an error
Use community discussions to identify what to investigate. Verify the actual limit, account state and error meaning using official documentation and your request logs.
Rate limit reached during a coding session
Is the limit from the account, workspace, model route, or gateway?
Check account limits, then lower concurrency and retry with a smaller context.API key versus Pro or Max subscription
Does the active authentication method use subscription access or API billing?
Treat subscription access and API billing separately unless the provider explicitly links them.500 or 529 during agent loops
Is the failure provider overload, a gateway route issue, or a repeating retry loop?
Record the status, request id, route, model, token size, and retry count before changing code.Start from the status code
Separate key and permission problems, quota limits, server errors, and overload before choosing a remedy.
Rate limit reached
The account, workspace, model or route has exceeded a request or token limit.
- Reduce parallel agent runs
- Trim long context
- Retry with backoff
- Check quota and model limits
API server error
The provider or route returned a server-side failure. Repeated failures need routing evidence.
- Capture the request id
- Retry once with backoff
- Compare another route if repeated
- Do not start by rewriting prompts
Overloaded
The upstream service is under heavy load. Replacing the API key usually will not fix overload.
- Wait and back off
- Try a fallback model
- Reduce request size
- Check status and support channels
API key or permission issue
The active key may be wrong or lack access to the model or endpoint.
- Confirm ANTHROPIC_API_KEY
- Check the base URL
- Verify model access
- Check the active billing source
Collect the facts before changing code
- Record the exact error, HTTP status, model, endpoint and time.
- Confirm whether you use a direct Anthropic key or a compatible gateway.
- Check API billing and quota separately from Pro or Max subscription status.
- For 429, reduce concurrency and context size first.
- For 500 or 529, retry once with backoff, then compare a route or fallback model.
- For a gateway, verify the Messages endpoint, model route, cache behavior and support guidance.
Pro or Max access and API billing are different
Check the active key, base URL and billing source. Do not assume subscription access and API credits share the same balance.
Get API accessUsing a gateway? Check the Messages endpoint
Claude-compatible clients need the appropriate Messages endpoint, a valid key and a model route supporting the requested workload.
Check the docsClaude Code API errors
Why does Claude Code say rate limit reached?
A request, token or model-route limit was exceeded. Check the active key, workspace, route, context size and parallel agent runs.
Does Pro or Max include an API key?
Treat subscription access and API billing separately unless the official account page says otherwise. Verify the active authentication method and billing source.
What should I do for API Error 500?
Record the request id and retry once with backoff. If failures repeat, compare a route or contact support with the time, model and request id.
What does 529 overloaded mean?
The upstream service is overloaded. Wait, back off, reduce request size or use a fallback route. A different API key usually does not fix overload itself.
Where to verify current rules
Official documentation is the authority for limits and error meanings. Community discussions are diagnostic leads, not a substitute for verified facts.