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 disabled model. Then the gateway answers with status 503 and the code model_disabled:

{"error": {
  "message": "Model 'gpt-5.4' is disabled",
  "code": "model_disabled"
}}

That is not a configuration mistake: the catalogue moved on and your config kept an old identifier. Replace it with an enabled model from the current list — for gpt-5.4 that is gpt-5.6-sol.

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 a free $0.50 test credit is available for subscribing to @zukkopro↗: link Telegram in the dashboard.