Common error codes explained: what 401, 403, 404, 429 and 500 each mean

Why a lookup table helps

The first reaction to an error is often that the site is down. But a good share of errors have nothing to do with the site. Some are your key, some are your request, some are your network.

The 4xx family: usually your side

400 Bad Request

Meaning: the request is malformed.

Common causes: invalid JSON, a missing required field, a wrong parameter type, context length exceeded.

Check first: the message field in the response body. Most sites explain what is wrong. Who to contact: yourself.

401 Unauthorized

Meaning: authentication failed.

Common causes: a typo or a stray space in the key, a revoked key, a malformed auth header such as a missing Bearer prefix, or using Anthropic's x-api-key where the site expects Authorization.

Who to contact: yourself.

403 Forbidden

Meaning: you are identified, but not permitted.

Common causes: the key was disabled by risk controls, an IP restriction triggered, or the model is outside your allowed range.

Easy to misdiagnose: Claude Code's Status 403 is often not a bad key but environment variables that did not take effect. Confirm that ANTHROPIC_BASE_URL is visible in the new terminal.

Who to contact: check it yourself first, then the site's support.

402, insufficient balance

Meaning: not enough funds. Check first: the balance in the site's dashboard. Who to contact: yourself.

404 Not Found

Two possibilities:

1. The endpoint is not implemented -- the site does not support the interface you called, such as /v1/responses
2. A misspelled model name

Check first:

curl https://your-endpoint/v1/models -H "Authorization: Bearer $KEY"

Then compare against the returned model ids.

429 Too Many Requests

Meaning: a rate or concurrency limit was triggered.

Common causes: too much concurrency in a short window, the per-account quota exhausted, or traffic classified as abnormal.

What to do: retry with exponential backoff and reduce concurrency. Do not retry immediately, because that only prolongs the throttling.

Who to contact: yourself, by lowering the rate. If throttling persists, ask support about the per-account ceiling.

The 5xx family: usually the site or its upstream

In these cases all you can do is switch to a backup channel.

When there is no status code

The difference between a connection timeout and a response timeout matters: with the former the request may never have left, so switching channels is safe. With the latter a charge may already exist, so switch with care.

An order of handling to follow

1. Read the message in the response body   <- most cases tell you what to change
2. Check the balance and key status        <- clears up many false site is down calls
3. Test with a minimal curl request        <- separates a request problem from a service problem
4. Change network, such as a phone hotspot <- rules out your local route
5. Check our monitoring page or the vendor group <- confirm whether the outage is widespread
6. Switch to a backup channel              <- restore the business first
7. Analyse the logs afterwards             <- do not do deep analysis mid-incident

The order of steps 6 and 7 is the key point. When production breaks, restore service first rather than starting the post-mortem on the spot.

One principle

Confirm whether the problem is yours alone.

If others see the same error, it is the site's problem and you only need to switch channels. If you are the only one, the problem is on your side and switching will not fix it.

Related reading

• A relay service starts erroring or slowing down: how to tell whose problem it is
• Claude Code with a relay service: full configuration and troubleshooting
• Configuring multiple API providers for failover