DEV Community

NiceAI
NiceAI

Posted on

Claude Code 401, 403, 404, 429 or 529: what does each error mean?

Short answer: 401 is a bad key, 403 is a valid key that isn't allowed to do this, 404 is almost always a wrong base URL, 429 means you're sending too much at once, and 529 means the upstream model is overloaded.

These five come up more than anything else when Claude Code is pointed at anything other than the default endpoint. The fixes apply to the official API, gateways and self-hosted proxies alike. The curl examples use api.niceai.dev as a sample host; replace it with your own.

Quick table

Error What it means First thing to try
401 Unauthorized The key is wrong Copy it again; look for stray spaces; check it isn't disabled
403 Forbidden Key is valid but not permitted Check balance; check the key's group includes this model
404 Not Found with /v1/v1/messages Base URL has an extra /v1 Set ANTHROPIC_BASE_URL to the bare host
400 model not found Model name doesn't exist for this key Copy the exact name from the provider's model list
400 prompt too long Conversation is over the context limit /compact, or start a new session
429 Too Many Requests Rate or concurrency limit Close extra sessions and sub-agents; wait a bit
529 overloaded_error Upstream model is busy Wait a few minutes or switch with /model
500 / 502 / 503 Temporary server or upstream issue Retry later; note the time if it keeps happening
"empty or malformed response" Got HTML instead of JSON Run the curl check below

Step 1: take the client out of the picture

Claude Code's error messages are often incomplete. One direct request tells you whose problem it is:

curl -sS -w '\n%{http_code}\n' https://api.niceai.dev/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"a-model-from-your-provider-list","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
Enter fullscreen mode Exit fullscreen mode
  • JSON with text in it: URL and key are fine. Look at your Claude Code settings.
  • HTML or a 404: the URL is wrong.
  • JSON 401: the URL is right, the key is wrong.
  • "model not found": URL and key are fine, the model name isn't.

Step 2: the usual suspects

404 and /v1. Claude Code appends /v1/messages to whatever you set. So ANTHROPIC_BASE_URL must be https://host, not https://host/v1. OpenAI-style tools (Codex, Cursor, Cline) are the opposite: they want /v1. Count how many times /v1 appears in the failing URL.

401 vs 403. 401 means "I don't know who you are". 403 means "I know who you are, but no". Don't rotate the key on a 403; check balance and model access first.

429 vs 529. 429 is about you: too many parallel sessions, or several people sharing one key. 529 is about the upstream: press Esc, wait, or switch models. Cranking up retries for either one only makes the queue longer.

Settings didn't change anything. Restart Claude Code after editing settings.json; running sessions keep the old values. If a value is in both settings.json and your shell, the file wins. /status shows the base URL Claude Code is actually using.

FAQ

Is 529 my fault? No. It's the model provider saying it's at capacity.

Why does a 404 mention /v1/v1/messages? Because /v1 is in your base URL and Claude Code added another one.

Can I see which URL Claude Code is calling? Yes, /status inside Claude Code.


The sample host in the commands is NiceAI; its docs keep a longer error-code reference at https://wiki.niceai.dev/guide/error-codes

Top comments (0)