Guides essentiels
Gérer les erreurs API
Lisez les codes d'erreur, ne réessayez que lorsque cela est utile et conservez l'ID de requête
Gérez les erreurs en fonction du statut HTTP et du code. Le message est rédigé pour les humains et peut changer sans préavis.
Les Chat Completions et les Responses utilisent un objet error de style OpenAI. Anthropic Messages et Gemini conservent leurs propres formats d'erreur ; n'utilisez donc pas un seul analyseur pour toute l'API TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Seuls message et type sont toujours présents dans les erreurs compatibles OpenAI créées par TokenLab. Les autres champs apparaissent lorsqu'ils sont pertinents.
Codes de statut
| Statut | Signification | Action typique |
|---|---|---|
400 | Un champ, un ID de modèle ou une entrée est invalide | Corrigez la requête ; ne la répétez pas telle quelle |
401 | La clé API est manquante, invalide, expirée ou révoquée | Remplacez la clé |
402 | Le solde ou la limite de la clé API est trop bas | Rechargez, augmentez la limite ou réduisez la requête |
403 | Cette clé ne peut pas utiliser la ressource ou le modèle, ou le compte est restreint | Modifiez les permissions de la clé ou le modèle, ou contactez le support |
404 | La ressource n'existe pas ou n'est plus disponible | Vérifiez l'ID et la clé API qui l'a créée |
409 | La Idempotency-Key a déjà été utilisée : avec un corps de requête différent (idempotency_conflict), ou pour une requête dont le résultat ne peut pas être renvoyé par TokenLab (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab n'a pas réexécuté la requête | Utilisez une nouvelle clé pour une nouvelle requête. Pour décider s'il faut réessayer avec la même clé, consultez Réessayer en toute sécurité avec une clé d'idempotence |
413 | La requête ou le fichier téléchargé est trop volumineux | Réduisez l'entrée selon la limite documentée du modèle ou du point de terminaison |
429 | Limite de requête atteinte | Attendez selon Retry-After |
500–504 | Service indisponible ou échec réseau | Réessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives |
Codes d'erreur courants
| Code | Signification | Que modifier |
|---|---|---|
invalid_api_key | La clé API est manquante, invalide, inactive ou révoquée | Vérifiez l'en-tête Authorization et la valeur de la clé |
expired_api_key | La clé a expiré | Créez ou sélectionnez une clé active |
insufficient_balance | Le solde du compte ne peut pas couvrir la requête | Ajoutez des fonds, réduisez la requête ou choisissez un modèle moins coûteux |
quota_exceeded | La clé API a atteint sa propre limite | Augmentez la limite de cette clé ou utilisez une autre clé autorisée |
model_not_allowed | La clé ne peut pas utiliser le modèle demandé | Mettez à jour la liste des modèles de la clé ou choisissez un modèle autorisé |
user_suspended, account_restricted | HTTP 403. Le compte ne peut pas utiliser l'API | Contactez le support avec l'ID de requête |
invalid_delivery_policy | HTTP 400. L'en-tête X-TokenLab-Delivery-Policy n'est pas auto, verified ou official | Envoyez l'une des trois valeurs ou supprimez l'en-tête |
model_not_found | L'ID du modèle est inconnu ou indisponible | Lisez /v1/models et utilisez un ID de modèle actuel |
context_length_exceeded | L'entrée est plus longue que ce que le modèle accepte | Supprimez l'historique ou choisissez un modèle avec une fenêtre de contexte plus grande |
missing_required_parameter | Un champ requis est manquant. param le nomme, par exemple model sur les requêtes audio et image, qui n'ont pas de modèle par défaut | Envoyez le champ nommé par param |
invalid_value | Un champ a une valeur que le modèle n'accepte pas, par exemple une valeur reasoning_effort. Le message liste les valeurs acceptées | Utilisez l'une des valeurs listées |
invalid_response_format_type | HTTP 400. response_format est un objet sans type exploitable, ou dont le type n'est pas accepté par cet endpoint. param vaut response_format | Définissez response_format.type sur text, json_object ou json_schema ; avec json_schema, envoyez aussi json_schema.name et json_schema.schema |
invalid_image_url | TokenLab ne peut pas utiliser une URL d'image : ce n'est pas une URL HTTP(S) valide ou un URI de données d'image, ou l'hôte de l'image n'a pas renvoyé l'image. param nomme le champ | Envoyez une URL d'image HTTPS publique ou un URI de données pris en charge |
unsupported_model_capability | Aucune route du niveau de livraison sélectionné ne prend en charge un paramètre de requête, tel que l'opération, resolution, aspect_ratio, duration, un champ média d'entrée, web_search_options ou max_tokens. Le message nomme chaque paramètre qui ne correspond pas et, lorsque le modèle les publie, les valeurs prises en charge | Supprimez ou modifiez le paramètre, ou choisissez un autre niveau de livraison ou modèle ; ne répétez pas la requête telle quelle |
unpriceable_selection | La requête vidéo omet un sélecteur dont dépend son prix, donc TokenLab ne peut pas la tarifer. param nomme le sélecteur | Définissez le champ nommé par param |
model_pricing_unavailable | HTTP 503. La requête est valide, mais TokenLab ne peut pas tarifer cette combinaison de modèle et d'opération sur les routes que la requête peut utiliser. La requête n'a pas été facturée et retryable est false | Ne répétez pas la requête telle quelle ; choisissez un autre modèle ou opération, ou contactez le support avec l'ID de requête |
idempotency_conflict | HTTP 409. La Idempotency-Key appartient à une requête différente. TokenLab n'a pas exécuté cette requête | Envoyez une nouvelle requête avec une nouvelle clé |
idempotency_replay_unavailable | HTTP 409. La Idempotency-Key a déjà été utilisée et TokenLab n'a aucun résultat à renvoyer pour celle-ci. TokenLab n'a pas réexécuté cette requête | Si la première requête peut encore être en cours, attendez et réessayez avec la même clé. Sinon, envoyez une nouvelle clé. Consultez Réessayer en toute sécurité avec une clé d'idempotence |
idempotent_response_not_replayable | HTTP 409. La Idempotency-Key appartient à une requête de création dont la tâche est déjà terminée, et TokenLab ne peut pas renvoyer la réponse de création originale. Le niveau supérieur du corps de la réponse inclut task_id, à côté de error. TokenLab n'a pas réexécuté cette requête | Ne répétez pas la requête avec cette clé. Envoyez une nouvelle clé uniquement si vous souhaitez une nouvelle tâche |
rate_limit_exceeded | Trop de requêtes ont été envoyées dans la fenêtre actuelle | Attendez selon Retry-After |
all_channels_failed | Le modèle sélectionné ne peut pas servir cette requête | Réessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives |
timeout_error | La requête n'a pas terminé à temps | Réessayez uniquement lorsque l'opération peut être répétée en toute sécurité |
Une erreur 503 all_channels_failed ou 503 delivery_tier_unavailable ne signifie pas toujours une panne temporaire. Si l'opération demandée n'est pas disponible dans le niveau de livraison sélectionné, retryable est false et retry_after est omis. Ne répétez pas la même requête. Vérifiez la disponibilité de l'opération et de la livraison avec GET /v1/models avant de sélectionner un autre modèle. Des noms similaires ne prouvent pas la disponibilité ; les alternatives non vérifiées sont omises.
Certaines erreurs compatibles OpenAI incluent des champs optionnels did_you_mean, suggestions, alternatives, hint, retryable ou retry_after. Consultez Erreurs sur lesquelles les agents peuvent agir.
Lorsqu'une requête a été exécutée sur une route officielle et que le service en amont a rejeté la requête elle-même, par exemple en raison d'une entrée qu'il n'accepte pas ou d'une décision de politique de contenu, l'erreur contient également upstream : le message de l'amont tel qu'il a été rapporté, plus le code et la source (le nom du service en amont) lorsqu'ils sont connus. Les erreurs Anthropic Messages et Gemini contiennent le même objet à l'intérieur de leur propre error. Continuez à baser votre logique sur code et type ; les valeurs upstream.code sont définies par le service en amont et peuvent changer.
Décisions de réessai
| Erreur | Répéter la même requête ? |
|---|---|
400, 401, 402, 403, 404, 413 | Non. Modifiez la requête, les identifiants, le solde, les permissions ou l'entrée. |
429 | Oui, après le délai fourni par le serveur. |
500–504 | Réessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives |
| Connexion fermée avant toute réponse | Oui, lorsque la requête est listée dans Réessayer en toute sécurité avec une clé d'idempotence et possède une Idempotency-Key : renvoyez-la avec la même clé et le même corps. Sinon, vérifiez d'abord si une tâche ou un effet secondaire existe déjà. |
| Flux interrompu après l'arrivée de la sortie | Ne considérez pas cela comme une réponse complète. La répétition peut générer une sortie différente ou une seconde facturation. |
Pour la création d'images, de vidéos, de musique, de 3D et de mondes, enregistrez l'ID de tâche dès qu'il est renvoyé. Si une requête de création expire, renvoyez-la avec la même Idempotency-Key et le même corps pour obtenir la tâche originale. Sans clé, vérifiez l'enregistrement de la tâche avant d'envoyer une autre requête de création.
Réessayer en toute sécurité avec une clé d'idempotence
Un délai d'attente ou une connexion fermée ne vous indique pas si TokenLab a exécuté la requête. Ajoutez un en-tête Idempotency-Key aux requêtes listées ci-dessous. Ainsi, un réessai de la même requête ne pourra pas l'exécuter ou la facturer une seconde fois.
- Utilisez une nouvelle valeur unique pour chaque opération, par exemple un UUID. Une clé peut comporter jusqu'à 255 caractères. TokenLab ignore une clé plus longue, et la requête n'a alors aucune protection d'idempotence : un réessai s'exécute et est facturé à nouveau.
POST /v1/messages/batchesest différent : il rejette une clé de plus de 256 caractères avec une erreur400. - Enregistrez la clé avec votre propre enregistrement de travail avant d'envoyer la requête.
- Lorsque vous réessayez, envoyez la même clé API, la même
Idempotency-Keyet le même corps. - Après toute réponse autre que
409avecidempotency_replay_unavailable, n'utilisez plus cette clé. Envoyez toute nouvelle tentative avec une nouvelle clé. - Désactivez les réessais du SDK (
max_retries=0), afin que votre code décide quand réutiliser une clé.
Sans l'en-tête, chaque réessai est une nouvelle requête.
Requêtes qui créent une tâche
Ces requêtes de création acceptent Idempotency-Key :
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsetPOST /v1/worlds/generationsPOST /v1/images/generationsetPOST /v1/images/editslorsqu'elles renvoient une tâchePOST /v1/responsesavec"background": truePOST /v1/messages/batches
Si une requête de création expire, renvoyez-la sans modification. TokenLab renvoie le résultat de la requête de création originale et ne crée, ne distribue ni ne facture une seconde tâche. Habituellement, le résultat est la tâche originale avec le même id (pour les Responses, l'objet de réponse original), et vous continuez à l'interroger. Pour les tâches vidéo, musique, 3D, mondes et images, le résultat peut également être l'erreur originale lorsque la première requête de création a échoué. Si une telle tâche est déjà terminée et que TokenLab n'a pas de réponse de création stockée, le réessai renvoie 409 avec le code idempotent_response_not_replayable, et le niveau supérieur du corps de la réponse inclut task_id.
Si vous envoyez un corps différent avec une clé que TokenLab a déjà acceptée, TokenLab rejette la requête et ne crée pas de tâche. Les requêtes de création vidéo, musique, 3D et mondes renvoient 409 avec le code idempotency_conflict. Message Batches renvoie 409 avec le type d'erreur conflict_error. Pour les tâches d'image et les requêtes Responses avec background: true, le code de statut et le code d'erreur pour ce cas ne sont pas garantis. Ne réessayez pas la requête avec la même clé.
Chat Completions, Responses et Messages
POST /v1/chat/completions, POST /v1/responses sans background et POST /v1/messages exécutent une requête avec une clé donnée une seule fois. Un réessai avec la même clé obtient l'un de ces résultats :
| Situation | Résultat |
|---|---|
| La première requête est toujours en cours | 409 avec le code idempotency_replay_unavailable |
| La première requête s'est terminée après la déconnexion de votre client. La requête n'a pas été diffusée en flux, le résultat fait 1 Mo ou moins, et vous réessayez avec le même corps dans les 24 heures | 200 avec le corps de réponse original et l'en-tête Idempotent-Replayed: true. TokenLab n'exécute ni ne facture à nouveau la requête |
| La clé a été utilisée d'une autre manière, par exemple : vous avez reçu le résultat, la requête a été diffusée en flux, le résultat faisait plus de 1 Mo, ou plus de 24 heures se sont écoulées | 409 avec le code idempotency_replay_unavailable |
| Le corps est différent de la première requête | 409, généralement avec le code idempotency_conflict. Certaines requêtes renvoient idempotency_replay_unavailable |
Un 409 avec l'un ou l'autre code signifie que TokenLab n'a pas réexécuté la requête. Une requête diffusée en flux avec une clé ne peut pas s'exécuter deux fois, mais TokenLab ne peut pas renvoyer sa sortie.
Cet exemple réessaie une requête Chat Completions ayant expiré avec la même clé jusqu'à ce qu'elle obtienne le résultat :
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Enregistrez cette clé avec votre enregistrement de travail.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # Aucune réponse : réessayez avec la même clé et le même corps.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# La première tentative peut toujours être en cours. Un réessai ultérieur renvoie son résultat.
raise RuntimeError(f"No result for Idempotency-Key {key}")Si la dernière tentative renvoie toujours idempotency_replay_unavailable, TokenLab ne peut pas renvoyer ce résultat. Envoyez la requête avec une nouvelle clé uniquement si une seconde exécution et une seconde facturation sont acceptables.
Conservez l'ID de requête
Les en-têtes de réponse incluent un ID de requête pour le suivi. Enregistrez-le avec le point de terminaison, le modèle, l'heure et votre propre ID utilisateur ou de travail. Pour le travail asynchrone, enregistrez également task_id et billing_transaction_id lorsqu'ils sont présents.
Lorsque vous contactez le support, incluez ces ID et un exemple expurgé. N'envoyez jamais de clés API, de jetons de gestion, de médias privés, d'URL signées ou de prompts privés complets.