Common connection errors and how to fix them

Almost every connection problem comes down to four things: the address, the key, the model ID and the balance. Start with the quick check below, then find your status code. The response bodies quoted here are the actual responses of the API (October 2026).

Quick check#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

If the first command fails, the cause can be the network on your side, a typo in the address — or the service itself being temporarily unavailable. If only the second one fails, look up its status code below. If both work but your tool doesn't, compare the tool's settings with these two commands.

401 — Invalid API key#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Clients in the Anthropic style get the same error in their format:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Causes:

• the key was copied with a missing character, a space or quotes;
• the key was rotated in the dashboard — the old one no longer works;
• a key from another service (for example OpenAI) is set instead of the CheapTokens key;
• the environment variable is empty in this terminal: echo ${#CHEAPTOKENS_API_KEY} prints its length.

The dashboard shows a key only once. If it's lost, press Rotate to get a new one and update it everywhere it's used.

402 — empty balance or no key in the request#

The API returns 402 in two different situations:

1. The balance is used up. Requests are paid from the balance; when it runs out, the key is paused. Top up in the dashboard and requests go through again.
2. The request has no key at all. If the Authorization header (or x-api-key for Anthropic-style clients) is missing, the API answers 402 with the type insufficient_funds. Check that your tool really sends the key: the OpenAI style is Authorization: Bearer <key>.

404 — wrong address#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

The path has a typo — here completion instead of completions. Other common causes:

• The base URL has no /v1. OpenAI-style clients need https://api.cheaptokens.dev/v1. Without /v1 the request misses the API and you get a plain HTML 404 page instead of JSON.
• /v1 twice. Some clients add /v1 themselves; then the base URL must be the root, https://api.cheaptokens.dev. Anthropic-style clients always use the root address.

400 — model not found#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

The model ID must be the full ID, including the prefix before the slash: deepseek-ai/DeepSeek-V4-Flash-0731, not deepseek-v4-flash. Upper or lower case doesn't matter. The error message lists the available IDs, and the full list is always at GET /v1/models.

A 400 also comes back for a malformed request body — for example an empty messages array (messages field is required and must be a non-empty array) or a message without role.

413 — request too large#

The request body is limited to 16 MB. Agents can hit it by putting huge files or logs into the context. Send only the parts the model needs and trim long tool output.

429 — too many requests#

If you receive 429, slow down. The response includes a Retry-After header with the number of seconds to wait. The official OpenAI SDKs retry automatically (max_retries); in your own code, wait for Retry-After before the next attempt.

503 — model temporarily unavailable#

A model can be temporarily unavailable; the API then answers 503 with the type model_unavailable, and the model card on the site shows "temporarily unavailable". Retry later or switch the model field to another model — the key and the address stay the same.

Long waits and timeouts#

Reasoning models such as zai-org/GLM-5.3-Flash think before answering, so the first token can take a while. Use streaming or raise the client timeout — for example timeout=120 in the OpenAI SDK.