Claude Code API errors and fixes: 401, 403, 404, 429, 5xx

Quick table: what each error means

Error	Meaning	Fix
401 Unauthorized	The key is wrong, disabled or deleted	Copy the key again from API Keys; check for spaces or a missing `sk-` prefix
403 Forbidden	Balance is too low, or this key cannot use this model	Top up, or use a model the key is allowed to call
404 Not Found	Model name is wrong, or the base URL is wrong	Copy the model name from models; use `https://api.macloudai.com` without `/v1`
429 Too Many Requests	Requests are coming too fast	Wait a few seconds and retry; avoid running many sessions in parallel
500 / 502 / 503 / 529	The upstream model had a temporary error	Wait a minute and retry, or switch to another model
Connection error / timeout	Network, proxy or VPN problem	Test with curl; check `HTTPS_PROXY` and your VPN

How do I find the actual cause?

Read the status code in the Claude Code error message (401, 403, 404, 429 or 5xx).
Run /status inside Claude Code and check the base URL and model it reports.
Test the same key and model with curl outside Claude Code (example below).
If curl works but Claude Code does not, the problem is how Claude Code loads its settings. If curl also fails, the problem is the key, balance, model name or network.
Fix the one setting that is wrong, open a new terminal, and start claude again.

curl https://api.macloudai.com/v1/messages \
  -H "x-api-key: sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "hk-5-5", "max_tokens": 50, "messages": [{"role": "user", "content": "ping"}]}'

This is the request Claude Code makes, so a correct JSON reply here means your key, balance and model name are fine.

401: invalid or missing key

The key was deleted in the console, or you pasted an old key. Create a new one in API Keys.
The value has extra characters: quotes inside quotes, a trailing space, or a line break from copying.
Both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set to different values. Remove one; keep ANTHROPIC_AUTH_TOKEN.
A key from another provider (for example from the official Anthropic console) is still set somewhere in your profile and overrides the new one.

403: balance or model permission

A 403 means the key is valid but the request is not allowed. Usually the balance is too low for the request. Open the console to see your balance and top up; requests work again as soon as the top-up is credited. If you have balance, check whether this key was limited to certain models, and use a model it can call.

404: wrong base URL or model name

This is the most common mistake. Claude Code uses the Anthropic format, and it adds /v1/messages to the base URL itself:

ANTHROPIC_BASE_URL	Result
`https://api.macloudai.com`	Correct
`https://api.macloudai.com/v1`	Wrong: requests go to /v1/v1/messages and fail
`https://api.macloudai.com/`	Usually works, but avoid the trailing slash

If the base URL is right, the model name is the next suspect. It must match the models page exactly, including dashes and version numbers. Claude Code may also call a second, smaller model for background tasks; if that name is not available on the gateway you can see 404 errors even though your main model is correct. Set it explicitly to a listed Claude model (in recent Claude Code versions the variable is ANTHROPIC_DEFAULT_HAIKU_MODEL; check the Claude Code docs for your version).

The /v1 rule is different for other tools. Cursor, Cline in OpenAI-compatible mode, n8n and the OpenAI SDK need https://api.macloudai.com/v1. Only Anthropic-format clients such as Claude Code and the Anthropic SDK use https://api.macloudai.com without it.

Environment variables not loaded

Symptoms: Claude Code asks you to log in, uses your old account, or /status shows the official API URL. Causes and fixes:

You set the variables in one terminal and started claude in another. Variables set with export or \$env: only apply to that window.
You added them to ~/.zshrc but your shell is bash (or the reverse). Check with echo \$SHELL.
On Windows you used setx but did not reopen the terminal or VS Code.
The IDE was started before you changed the profile. Restart the IDE completely.
Your ~/.claude/settings.json has a JSON syntax error, so it is ignored. Validate it with any JSON checker.

The most reliable fix is to put the values in the env block of ~/.claude/settings.json, as shown in the setup guide.

Proxy, VPN and network errors

Errors such as ECONNRESET, ETIMEDOUT, fetch failed or certificate errors are not from the gateway; the request never arrived. Check these:

If you are behind a corporate proxy, set HTTPS_PROXY (and HTTP_PROXY) to the proxy address, the same way you set the other variables.
Some VPNs or firewalls block or inspect HTTPS traffic. Try once with the VPN off, or add an exception for https://api.macloudai.com.
A corporate network that replaces TLS certificates needs its root certificate trusted by Node.js (for example through NODE_EXTRA_CA_CERTS). Ask your IT team.
Run the curl test above from the same machine. If curl also times out, it is a network issue, not a Claude Code issue.

429 and 5xx: retry, then switch

A 429 means requests came in too fast, which happens with several Claude Code sessions or sub-agents running at once. Wait a few seconds and continue; Claude Code retries some errors on its own. A 5xx means the upstream model had a temporary problem. Wait a minute and try again, or switch ANTHROPIC_MODEL to another Claude model from the models page for a while.

Checklist before you ask for help

ANTHROPIC_BASE_URL is exactly https://api.macloudai.com (no /v1).
ANTHROPIC_AUTH_TOKEN is a current key from the console, starting with sk-, with no spaces or quotes inside.
ANTHROPIC_API_KEY is not set to some other value.
ANTHROPIC_MODEL is copied from the models page.
Your balance is above zero.
The curl test returns a normal reply from the same machine.
You opened a new terminal after changing the variables.

If all of these are fine and the error continues, note the time, the model and the status code and contact support from the console. Full integration docs are at /docs.

FAQ

Q1Why do I get 404 even though the model name is right?

Usually because ANTHROPIC_BASE_URL ends in /v1. Claude Code adds /v1/messages itself, so use https://api.macloudai.com without /v1.

Q2Claude Code keeps asking me to log in. What is wrong?

It is not seeing your environment variables. Open a new terminal, check that the variables are set there, or put them in the env block of ~/.claude/settings.json.

Q3What does 403 mean on MaCloud AI?

The key is valid but the request is not allowed: usually the balance is too low, or the key is not allowed to use that model. Top up or change the model.

Q4Is a 5xx error charged?

Calls that fail upstream do not return a completion. Check the Usage page in the console, which lists every billed call with its tokens and cost.

Q5Does a VPN cause errors?

It can. Connection resets, timeouts and certificate errors usually come from a VPN, proxy or firewall. Test with curl and try once without the VPN.