Claude API errors: 401, 404, 429 and 529, diagnosed
Almost every Claude API error reduces to four causes: the wrong auth header, a doubled version segment in the URL, a missing required parameter, or a model ID that does not exist on the endpoint. Check those before anything else.
curl https://aicomp.ai/v1/models \
-H "Authorization: Bearer sk-your-gateway-key"A JSON list of model IDs means the key is good. Invalid token means it was copied wrong.
Fast diagnosis table
| Status / error | Usual cause | Fix |
|---|---|---|
| 401 authentication_error | Wrong or truncated key, or wrong header | Use x-api-key and include anthropic-version |
| 404 not_found_error | Doubled /v1, or unknown model | Check the base URL and the exact model ID |
| 400 invalid_request_error | max_tokens missing | Add it — it is required on this API |
| 429 rate_limit_error | Your quota on requests or tokens | Exponential backoff with jitter |
| 529 overloaded_error | Upstream under load | Retry with backoff; not your quota |
| 413 / context length | Prompt longer than the window | Compact history or trim context |
| 500 api_error | Server-side fault | Retry once, then alert if it persists |
401 — the header, not the key
The single most common failure when moving from an OpenAI-shaped integration. This API expects:
curl https://aicomp.ai/v1/messages \
-H "x-api-key: $API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5","max_tokens":64,
"messages":[{"role":"user","content":"say OK"}]}'Sending Authorization: Bearer instead returns 401 even with a perfectly valid key.
404 — the doubled segment
If your base URL ends in /v1 and your client appends /v1/messages, the request
becomes /v1/v1/messages. Remove the suffix from whichever side is duplicating it — never from both.
400 — required parameters
max_tokens is mandatory. Requests that omit it are rejected before anything else is evaluated,
which is why this error can appear even when everything else is correct.
429 and 529 — retries done properly
import time, random
def with_retry(fn, retries=5):
delay = 1.0
for _ in range(retries):
try:
return fn()
except RateLimitError:
time.sleep(delay + random.uniform(0, 0.3))
delay *= 2
raiseNever retry a 400 — it will fail identically every time. Retry 429, 529 and 500. See rate limits explained for the full picture.
Model not found
Model IDs differ between providers and sometimes include date suffixes. Copy the exact string from the endpoint's own listing rather than from documentation or memory:
curl https://aicomp.ai/v1/models -H "Authorization: Bearer sk-your-gateway-key"Still stuck
Reproduce with curl from the same machine your app runs on. If curl works and your app does not, the problem is in your client — headers, base URL, or an environment variable that never reached the process.
FAQ
Why do I get a 401 with a key that works elsewhere?
Almost always the header. The Anthropic API authenticates with x-api-key and expects an anthropic-version header, not Authorization: Bearer. Keys are also easy to truncate when copying.
Why 404 on a path that looks correct?
A doubled version segment. If your base URL already ends in /v1, do not add it again before /messages — the request becomes /v1/v1/messages and returns 404.
What does 'max_tokens is required' mean?
Exactly that: unlike the OpenAI API, where the field is optional, this API rejects requests without it. Add max_tokens to every call.
Is a 429 the same as a 529?
No. A 429 means you hit your own rate limit and should back off; a 529 means the upstream is overloaded. Both warrant retry with backoff, but only the first is about your quota.
How do I tell whether the endpoint or my code is at fault?
Reproduce with curl from the same machine. If curl succeeds and your app fails, the problem is in your client configuration — headers, base URL or environment variables.