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. 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 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"}]}' 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. 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. 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
Key Takeaways #
- •The fixes apply to the official API, gateways and self-hosted proxies alike.
- •This story was reported by Dev.to , covering developments in thedev space.
- •AI advancements continue to reshape industries — read the full article on Dev.to for complete coverage.
📖 Continue reading the full article: