Common API connection errors and how to read them

Connecting to a compatible API usually takes a couple of minutes, and when it does not, the cause is almost always one of four things. Here is how to read the server's response and what to fix.

401 — the key was rejected

{"error": {"message": "Unauthorized", "type": "authentication_error"}}

What to check, in order.

Whitespace around the key. Copying from a messenger often attaches a space or a newline. The key must follow Bearer immediately.

The variable name. Claude Code wants ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY — with the latter it assumes an official account and asks you to log in. Codex looks for the key in ~/.codex/auth.json under the name OPENAI_API_KEY regardless of provider.

A revoked key. Keys are shown once at creation. If you are unsure you saved the right one, issue a new one — cheaper than guessing.

Valid JSON. In settings.json a trailing comma quietly invalidates the whole file, and the variables simply never arrive.

402 — empty balance

{"error": {"message": "Insufficient balance", "code": "insufficient_balance"}}

The most honest of the errors: there is no money in the account and the request never reached a model. Top up and retry — restarting your tool is unnecessary.

Worth knowing: the balance check happens before the upstream call, so a failed request costs nothing.

404 — almost always a stray or missing /v1

This is the most common first-connection error, and it is not about the key.

Anthropic-compatible clients — Claude Code, the Anthropic SDK, Roo Code — use the address without a suffix: https://api.zukko.pro. They append the path themselves.

OpenAI-compatible ones — Cursor, Codex, Cline, the OpenAI SDK — use it with the suffix: https://api.zukko.pro/v1.

Get it backwards and every request lands on a path that does not exist. The symptom is distinctive: the key is accepted, but every call returns 404.

Model not found

{"error": {"message": "The model 'gpt-4o' does not exist", "code": "model_not_found"}}

The name does not match the catalogue. Case and the dots in version numbers matter: claude-sonnet-5, not Claude-Sonnet-5 and not claude sonnet 5.

The current list is available without a key:

curl https://api.zukko.pro/v1/models

A separate case is a retired model. Then the response names the replacement directly:

{"error": {
  "message": "Model 'gpt-5.4' has been retired. Use 'gpt-5.6-terra'",
  "code": "model_retired"
}}

That is not a configuration mistake: the catalogue moved on and your config kept an old identifier.

Requests go out but nothing happens

If a tool stays silent, check that it is calling your address at all rather than its default provider. In Claude Code, asking any question is enough — the first answer confirms billing runs against your balance, because the spend appears in your dashboard history.

A quick connectivity check

Before digging through a tool's configuration, confirm the key works on its own:

curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_your_key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

An answer means the problem is in your tool's settings, not in access. No answer, and the error text tells you what to fix.

Keys are issued in the dashboard, and the starting dollar for testing is credited on first sign-in to @zukkopro_bot↗.