Guides

Errors

Every error code of the compatible API, its cause, what it costs and what to do, with the request identifier to send to support.

Verified on 4 October 2026Markdown version Report a problem on this page

Errors keep the shape of the SDK you use, so that it reads them without adaptation.

Réponse 401

{
  "error": {
    "message": "Invalid API key. Provide a Tukai key as `Authorization: Bearer tuk_sk_…` or `x-api-key`.",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

On the Anthropic side, the same error has the shape {"type": "error", "error": {"type": "authentication_error", "message": "…"}}.

Read the type field, never the message text: depending on the cause, the message is in English (authentication and validation errors) or in French (refusals related to your plan or to rate limits).

Code table

Status	OpenAI type	Anthropic type	Causes	What to do
400	`invalid_request_error`	`invalid_request_error`	The model is ticked on the key but is not served	Choose a model from the Models (French) page
401	`authentication_error`	`authentication_error`	Key missing, unknown, revoked or expired	Check the key; create a new one if it was revoked
402	`insufficient_quota`	`billing_error`	No subscription and no credits on the account	Top up, then retry the same request
403	`permission_error`	`permission_error`	Model not ticked on the key; model not included in your plan; context or request too long for your plan	Edit the key, choose another model or shorten the request
413	`invalid_request_error`	`request_too_large`	Request body too large	Reduce the content sent
422	`invalid_request_error`	`invalid_request_error`	Empty `messages`, missing `model`, field of the wrong type; on the Anthropic side, missing `max_tokens`	Fix the request
429	`rate_limit_error`	`rate_limit_error`	Key rate limit (30 requests per minute); key monthly cap reached; your plan's usage limits (session, weekly or subscription period windows, rate, concurrent requests)	Wait (`retry-after`), raise the key's cap, or wait for the plan's next window
500	`server_error`	`api_error`	Internal error	Retry later; report it with the `x-request-id`
502	—	—	The API cannot be reached from the published address (response from the relay, not from the API)	Retry later
503	`server_error`	`api_error`	Generation service unavailable; cap counter unreadable (the call is refused rather than let through uncounted)	Retry later
504	`server_error`	`api_error`	The model provider did not respond in time	Retry, or change the model

What is billed

A refusal (400 to 429) is never billed: it happens before generation.
An error before the first generated word is not billed.
An error after generation has started is billed in proportion to what was produced.
A successful generation is billed, even if your program did not read the response to the end: cutting the connection mid-stream stops neither the generation nor its billing.

Error in the middle of a stream

In streaming, the response has already started with a 200 status when an error can occur. The error then arrives in the stream, with the same envelope as above. Your code must read each event, not just the HTTP status.

Retry without paying twice

Do not retry automatically on 400, 401, 402, 403, 413 or 422: the same request will fail the same way.
On 429, 500, 502, 503 and 504, retry with an increasing delay and a bounded number of attempts.
The compatible API does not accept an Idempotency-Key header: if a generation succeeded but the response was lost on the way, retrying it produces a second, billed generation. Keep generous timeouts rather than retrying quickly.

Reporting an error to support

Send to service-client@tukhnanutha.com:

the value of the response's x-request-id header;
the date and time, with the time zone;
the model identifier and the operation (/v1/chat/completions or /v1/messages);
the status and the error type;
the SDK and its version.

The Help (French) page prepares this message for you. Never send your key, nor the content of your messages if you would rather not.