Debugging an integration spends half its time on one question: which side broke. Let's go through the codes.
401: key rejected
The key is wrong, revoked or never sent. Check in order:
- The header name. Anthropic uses
x-api-key, the OpenAI-compatible format usesAuthorization: Bearer. - The key itself. It is easy to truncate on copy or pick up a trailing newline.
- The environment variable. It has to reach the process, not just sit in your shell.
The third one trips up the most people: it works locally and fails in Docker.
400: request not parsed
The model is not the problem, the request body is. Typical causes:
- an unknown model name, for example a retired one
max_tokensabove the model's limit- message roles that do not alternate
- an empty messages array
Retrying will not help. Fix the request itself.
429: rate limited
You hit the limit on requests or tokens per minute. There is one right reaction: wait and retry, growing the delay and adding jitter. We have a separate write-up on limits.
500: provider-side failure
Not your bug. Retrying is fine and advisable, just with a delay. But if the failure reproduces reliably on one particular request, the input is the likelier culprit: a context that is too long or a broken encoding.
529 and overloaded
The service is saturated. It differs from a 500 in being temporary: a retry a few seconds later almost always goes through.
On agentic runs, plan for it in advance. An agent that dies on its first overloaded loses the whole task context.
Telling quickly whose fault it is
A rough rule: 4xx codes point at you, 5xx codes at the service.
The exception is 429. The fault is formally yours, but waiting cures it, not 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, and without it the conversation turns into guesswork.
If you go through a gateway
Provider errors reach you from us unchanged, so diagnosis stays the same. The dashboard also shows per-key stats, including the share of failed requests, and live service numbers sit on the status page.