Skip to content
AI Tokens Docs

API reference

Errors

The shapes errors come in, the statuses the API really returns, and which ones are worth retrying.

Last updated: 2026-10-11

On /v1, most errors have the OpenAI shape:

json
{
  "error": {
    "message": "unknown tier: turbo",
    "type": "invalid_request_error"
  }
}

message and type are always there. Depending on the error you also get code, param (the field at fault) and request_id. The app API has its own codes, listed in Authentication.

Messages are in English on every brand, on /v1 and on the app API, and say what to do. Write your code against the HTTP status, type and code, not against the text: the wording can change.

Three errors with a different shape

These three are produced by the framework the API is built on, and have a message at the top level; the first of them also has the error object.

Validation of chat completions, 422: a required field missing, or a value out of range (max_tokens above 8192, an unknown role). Since 11 October 2026 it also carries the error object, with the first field at fault in param; the keys of errors are all the fields at fault:

json
{
  "error": {
    "message": "…",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "invalid_value"
  },
  "message": "…",
  "errors": {
    "max_tokens": ["…"]
  }
}

Rate limit of an endpoint, 429:

json
{ "message": "Too Many Attempts." }

Unexpected error on our side, 500:

json
{ "message": "Server Error" }

Status codes

HTTP type / code When What to do
400 invalid_request_error A parameter we do not recognise or refuse, named in param (the list); an image we cannot accept; an unknown X-Siati-Tier. On embeddings, rerank, audio and responses, also a missing or invalid field Fix the request
401 invalid_request_error, code invalid_api_key Key missing, malformed, unknown, revoked or expired, or account disabled See Authentication
402 type and code insufficient_credits No credits left, on a brand with prepaid credits. Requests with GET still answer Write to info@daikolab.ch for more credits: retrying does not help
402 type and code spending_limit_reached The key has a monthly spending limit, and this request's highest cost does not fit in what is left of it this month. The message gives the reserve, the model and what is left. Nothing was sent to a model Raise the limit in the dashboard, or lower max_tokens: retrying does not help until the month turns
404 invalid_request_error, code unknown_endpoint The path does not exist, or exists for another method: GET /v1/chat/completions gets 404, not 405 Check path and method
404 type model_not_found The model is not in the catalogue GET /v1/models lists the valid ones
422 invalid_request_error, code invalid_value Chat completions: a required field missing or out of range Fix the field in param; all of them are in errors
429 type rate_limit_exceeded, or Too Many Attempts. The limit of the tier, or of the endpoint: both count per key Wait Retry-After seconds. See Rate limits
500 usually none, see above A bug on our side Retry once; if it repeats, write to us
501 code stream_not_implemented "stream": true on /v1/responses Stream with chat completions
501 type not_implemented /v1/rerank where it is turned off —
502 type bad_gateway The machines that could serve the request did not answer Retry after a short wait
503 type zone_unavailable No machine for the model is available in your key's zones. The message names the zones: we do not move the request elsewhere Retry later. If it persists, your key may have no zone where that model runs: write to info@daikolab.ch
503 type model_unavailable No machine for the model is available Retry later, or use another model
503 type model_activation_required The model is in the catalogue on request, and is not loaded now Retrying will not help: write to info@daikolab.ch

zone_unavailable, model_unavailable and model_activation_required come from text generation (chat completions and responses). When one machine fails, the request has already moved to the next one in your zones: a 502 means none of them answered.

Errors in a stream

Once a stream has started the status is 200, and an error arrives as an event with an error object; the stream then ends without [DONE]. See Streaming.

What is charged

A request refused with a 4xx costs nothing, and neither does a request that ends in 502. When a machine fails and the next one answers, you pay once, for the answer you received.

Retrying

Status Retry?
429 Yes, after Retry-After seconds
502, 503 model_unavailable, 503 zone_unavailable Yes, after a wait that grows at each attempt
500 Once
400, 401, 402, 404, 422, 501, 503 model_activation_required No: the same request fails the same way

A retry is a new request: it counts against your rate limits.

Reporting a problem

Every response carries an X-Request-Id header: the reference we record the request under. The request_id inside an error is the same value. Send it to info@daikolab.ch with the time of the request; for a chat completion, add the id of the answer too. If you send your own X-Request-Id, we keep it in our logs next to ours, but the answer carries ours. curl -i shows the headers:

bash
curl -i https://api.aitokens.ch/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.8-27b", "messages": [{"role": "user", "content": "Hello"}]}'

Common mistakes

  • curl without Content-Type: application/json. The body is read as a form, and you get 422 saying that model and messages are missing. The OpenAI SDKs set the header for you.
  • A body that is not valid JSON. Same 422: the body is read as empty.
  • The wrong method. GET on an endpoint that takes POST answers 404 unknown_endpoint.
  • /v1/rag/… with an API key. It does not exist and answers 404. With a key, knowledge bases are at /v1/knowledge-bases, to list them and ask questions; creating them and uploading documents need the app API, with a user token. See Who can do what.
  • A user token on /v1. It answers 401 with invalid api key format: /v1 takes API keys only.

Search the docs

Type to search…