Home / When things go wrong

API errors and rate limits

An API error carries a status code that tells very different causes apart: a malformed request must be corrected before any retry, whereas a temporary rate limit resolves by respecting Retry-After. A spending cap reached carries no such header, and waiting achieves nothing: the cap itself must be raised.

An error returned by the Anthropic API carries a status code that distinguishes very different causes. A 400 error, invalid_request_error, or a 404, not_found_error, signals a malformed request: an invalid parameter, incorrect content, or a model identifier that no longer exists as written. Retrying that call without correcting it reproduces the same error indefinitely, the only way out is to bring the call back in line with the specification currently in force. A model identifier that has changed name since a script was written explains a good part of these 400 and 404 errors: the current documentation for the model in use remains the first thing to open before suspecting anything else. A 400 is not always a malformed request, however: the API also returns this code when usage reaches a spending cap set for the organisation or the workspace, except on the Claude Code workspace, which can then return a 429 instead. In that particular case, correcting the request achieves nothing, it is the cap itself that must be raised.

Not every 429 error resolves itself by waiting

A 429 error, rate_limit_error, signals a cap being reached, but two distinct caps produce this same code. A temporary rate that has been exceeded carries a Retry-After header and resolves itself by respecting the delay it indicates before retrying. A spending cap reached for a tier, on the other hand, carries no Retry-After header at all: the documentation says so, such a 429 keeps failing without let-up until access is restored. Waiting achieves nothing here: retrying wastes calls and delays the real solution, which is raising the cap set by the organisation before resuming the sending of requests.

HTTP/1.1 429 Too Many Requests
retry-after: 12

{"type":"error","error":{"type":"rate_limit_error"}}

The presence or absence of this header, not the 429 code alone, decides between waiting and acting otherwise.

In Claude Code, two variables govern the retries

A 529 error, overloaded_error, displays a message in Claude Code stating that the API is at full capacity, without touching the session's usage quota. A series of 529 errors can look alarming without actually eating into the volume of usage the subscription allows. Claude Code automatically retries 429 and 529 errors of the temporary rate type, never a 429 caused by a gateway's spending cap. CLAUDE_CODE_MAX_RETRIES bounds the number of attempts, CLAUDE_CODE_RETRY_WATCHDOG allows retrying indefinitely in an unsupervised session: the figure accompanying this lesson gives the exact values.

The same choice between waiting and acting comes up in a stuck command, facing a silence that could signal a genuine stall or work still in progress.