# Erreurs

> Chaque code d'erreur de l'API compatible, sa cause, ce qu'il coûte et ce qu'il faut faire, avec l'identifiant de requête à transmettre au support.

Source : https://developers.tuk-ai.com/docs/errors · Vérifié le 2026-10-04

Les erreurs gardent la forme du SDK que vous utilisez, pour qu'il les lise sans 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
  }
}
```

Côté Anthropic, la même erreur a la forme `{"type": "error", "error": {"type": "authentication_error", "message": "…"}}`.

**Lisez le champ `type`, jamais le texte du message** : selon la cause, le message est en anglais (erreurs d'authentification, de validation) ou en français (refus liés à votre offre ou au débit).

## Table des codes

| Statut | Type OpenAI | Type Anthropic | Causes | Que faire |
|---|---|---|---|---|
| 400 | `invalid_request_error` | `invalid_request_error` | Le modèle est coché sur la clé mais n'est pas servi | Choisir un modèle de la page [Modèles](https://developers.tuk-ai.com/models) |
| 401 | `authentication_error` | `authentication_error` | Clé absente, inconnue, révoquée ou expirée | Vérifier la clé ; en créer une nouvelle si elle a été révoquée |
| 402 | `insufficient_quota` | `billing_error` | Ni abonnement ni crédit sur le compte | [Recharger](https://chat.tuk-ai.com/pay/checkout), puis relancer la même requête |
| 403 | `permission_error` | `permission_error` | Modèle non coché sur la clé ; modèle non inclus dans votre offre ; contexte ou requête trop longs pour votre offre | Modifier la clé, choisir un autre modèle ou raccourcir la requête |
| 413 | `invalid_request_error` | `request_too_large` | Corps de requête trop volumineux | Réduire le contenu envoyé |
| 422 | `invalid_request_error` | `invalid_request_error` | `messages` vide, `model` absent, champ du mauvais type ; côté Anthropic, `max_tokens` absent | Corriger la requête |
| 429 | `rate_limit_error` | `rate_limit_error` | Débit de la clé (30 requêtes par minute) ; plafond mensuel de la clé atteint ; limites d'usage de votre offre (fenêtres de session, de semaine ou de période d'abonnement, débit, requêtes simultanées) | Attendre (`retry-after`), relever le plafond de la clé, ou attendre la fenêtre suivante de l'offre |
| 500 | `server_error` | `api_error` | Erreur interne | Réessayer plus tard ; signaler avec le `x-request-id` |
| 502 | — | — | L'API est injoignable depuis l'adresse publiée (réponse du relais, pas de l'API) | Réessayer plus tard |
| 503 | `server_error` | `api_error` | Service de génération indisponible ; compteur de plafond illisible (l'appel est refusé plutôt que laissé passer sans compter) | Réessayer plus tard |
| 504 | `server_error` | `api_error` | Le fournisseur du modèle n'a pas répondu à temps | Réessayer, ou changer de modèle |

## Ce qui est facturé

- Un **refus** (400 à 429) n'est jamais facturé : il intervient avant la génération.
- Une erreur **avant le premier mot généré** n'est pas facturée.
- Une erreur **après le début de la génération** est facturée au prorata de ce qui a été produit.
- Une génération **réussie** est facturée, y compris si votre programme n'a pas lu la réponse jusqu'au bout : couper la connexion en cours de flux n'arrête ni la génération ni sa facturation.

## Erreur au milieu d'un flux

En streaming, la réponse a déjà commencé avec un statut `200` quand une erreur peut survenir. L'erreur arrive alors **dans le flux**, avec la même enveloppe que ci-dessus. Votre code doit lire chaque événement, pas seulement le statut HTTP.

## Réessayer sans payer deux fois

- Ne réessayez pas automatiquement sur `400`, `401`, `402`, `403`, `413` ou `422` : la même requête échouera de la même façon.
- Sur `429`, `500`, `502`, `503` et `504`, réessayez avec un délai croissant et un nombre d'essais borné.
- L'API compatible n'accepte pas d'en-tête `Idempotency-Key` : si une génération a réussi mais que la réponse s'est perdue en route, la relancer produit une **seconde génération, facturée**. Gardez des délais d'attente généreux plutôt que de relancer vite.

## Transmettre une erreur au support

Envoyez à [service-client@tukhnanutha.com](mailto:service-client@tukhnanutha.com) :

- la valeur de l'en-tête `x-request-id` de la réponse ;
- la date et l'heure, avec le fuseau ;
- l'identifiant du modèle et l'opération (`/v1/chat/completions` ou `/v1/messages`) ;
- le statut et le `type` d'erreur ;
- le SDK et sa version.

La page [Aide](https://developers.tuk-ai.com/support) prépare ce message pour vous. N'envoyez **jamais** votre clé, ni le contenu de vos messages si vous n'y tenez pas.