# 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.

Source : https://developers.tuk-ai.com/en/docs/errors · Verified on 2026-10-04

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

Réponse 401 :

```json
{
  "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](https://developers.tuk-ai.com/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](https://chat.tuk-ai.com/pay/checkout), 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](mailto: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](https://developers.tuk-ai.com/support) (French) page prepares this message for you. **Never** send your key, nor the content of your messages if you would rather not.