Claude API errors: what each code means and what to do

401, 400, 429, 500, 529 and overloaded explained: the cause of each, which are worth retrying, and how to tell your bug from the provider's.

Half the time spent debugging an integration goes into working out whose fault it is. Here it is by code.

401, key rejected

The key is wrong, revoked or missing. Check three things in order:

The header name is right. Anthropic uses x-api-key, the OpenAI-compatible format uses Authorization: Bearer.
The key was not truncated on copy and has no trailing newline.
The environment variable actually reached the process rather than staying in your shell.

That last one catches the most people: works locally, fails in Docker.

400, request not parsed

Nothing to do with the model, the body is wrong. Common causes:

an unknown model name, for example a retired one
max_tokens above what the model supports
message roles not alternating
an empty messages array

Retrying is pointless, fix the request.

429, rate limited

You exceeded requests or tokens per minute. The only correct reaction is to wait and retry with growing delay and jitter. We have a separate write-up on limits.

500, provider-side failure

Not your bug. Retrying is fine and advisable, with a delay. If it reproduces reliably on one specific request, the input is probably at fault after all: context too long or broken encoding.

529 and overloaded

The service is saturated. Unlike a 500 this is temporary and almost always clears on a retry a few seconds later.

On agentic runs it is worth handling deliberately: an agent that dies on the first overloaded loses the whole task context.

Telling quickly whose fault it is

Simple rule: 4xx is you, 5xx is the service.

The exception is 429. Formally yours, but cured by waiting rather than by editing code.

What to log

The minimum that saves hours:

status code, model name, request id,
input size in tokens, first 200 chars of the error body

The request id matters most: with it support finds the problem in minutes, without it the conversation becomes guesswork.

Through a gateway

We pass provider errors through unchanged, so diagnosis does not change. The dashboard also shows per-key stats including the share of failed requests, and live service numbers sit on the status page.