TokenLab

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

StatutSignificationAction typique
400Un champ, un ID de modèle ou une entrée est invalideCorrigez la requête ; ne la répétez pas telle quelle
401La clé API est manquante, invalide, expirée ou révoquéeRemplacez la clé
402Le solde ou la limite de la clé API est trop basRechargez, augmentez la limite ou réduisez la requête
403Cette clé ne peut pas utiliser la ressource ou le modèle, ou le compte est restreintModifiez les permissions de la clé ou le modèle, ou contactez le support
404La ressource n'existe pas ou n'est plus disponibleVérifiez l'ID et la clé API qui l'a créée
409La 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êteUtilisez 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
413La requête ou le fichier téléchargé est trop volumineuxRéduisez l'entrée selon la limite documentée du modèle ou du point de terminaison
429Limite de requête atteinteAttendez selon Retry-After
500–504Service indisponible ou échec réseauRéessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives

Codes d'erreur courants

CodeSignificationQue modifier
invalid_api_keyLa clé API est manquante, invalide, inactive ou révoquéeVérifiez l'en-tête Authorization et la valeur de la clé
expired_api_keyLa clé a expiréCréez ou sélectionnez une clé active
insufficient_balanceLe solde du compte ne peut pas couvrir la requêteAjoutez des fonds, réduisez la requête ou choisissez un modèle moins coûteux
quota_exceededLa clé API a atteint sa propre limiteAugmentez la limite de cette clé ou utilisez une autre clé autorisée
model_not_allowedLa 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_restrictedHTTP 403. Le compte ne peut pas utiliser l'APIContactez le support avec l'ID de requête
invalid_delivery_policyHTTP 400. L'en-tête X-TokenLab-Delivery-Policy n'est pas auto, verified ou officialEnvoyez l'une des trois valeurs ou supprimez l'en-tête
model_not_foundL'ID du modèle est inconnu ou indisponibleLisez /v1/models et utilisez un ID de modèle actuel
context_length_exceededL'entrée est plus longue que ce que le modèle accepteSupprimez l'historique ou choisissez un modèle avec une fenêtre de contexte plus grande
missing_required_parameterUn 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éfautEnvoyez le champ nommé par param
invalid_valueUn champ a une valeur que le modèle n'accepte pas, par exemple une valeur reasoning_effort. Le message liste les valeurs acceptéesUtilisez l'une des valeurs listées
invalid_response_format_typeHTTP 400. response_format est un objet sans type exploitable, ou dont le type n'est pas accepté par cet endpoint. param vaut response_formatDé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_urlTokenLab 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 champEnvoyez une URL d'image HTTPS publique ou un URI de données pris en charge
unsupported_model_capabilityAucune 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 chargeSupprimez 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_selectionLa requête vidéo omet un sélecteur dont dépend son prix, donc TokenLab ne peut pas la tarifer. param nomme le sélecteurDéfinissez le champ nommé par param
model_pricing_unavailableHTTP 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 falseNe 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_conflictHTTP 409. La Idempotency-Key appartient à une requête différente. TokenLab n'a pas exécuté cette requêteEnvoyez une nouvelle requête avec une nouvelle clé
idempotency_replay_unavailableHTTP 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êteSi 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_replayableHTTP 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êteNe répétez pas la requête avec cette clé. Envoyez une nouvelle clé uniquement si vous souhaitez une nouvelle tâche
rate_limit_exceededTrop de requêtes ont été envoyées dans la fenêtre actuelleAttendez selon Retry-After
all_channels_failedLe modèle sélectionné ne peut pas servir cette requêteRéessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives
timeout_errorLa requête n'a pas terminé à tempsRé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

ErreurRépéter la même requête ?
400, 401, 402, 403, 404, 413Non. Modifiez la requête, les identifiants, le solde, les permissions ou l'entrée.
429Oui, après le délai fourni par le serveur.
500–504Réessayez uniquement lorsque retryable est true ; respectez retry_after et limitez les tentatives
Connexion fermée avant toute réponseOui, 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 sortieNe 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/batches est différent : il rejette une clé de plus de 256 caractères avec une erreur 400.
  • 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-Key et le même corps.
  • Après toute réponse autre que 409 avec idempotency_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/generations et POST /v1/worlds/generations
  • POST /v1/images/generations et POST /v1/images/edits lorsqu'elles renvoient une tâche
  • POST /v1/responses avec "background": true
  • POST /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 :

SituationRésultat
La première requête est toujours en cours409 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 heures200 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ées409 avec le code idempotency_replay_unavailable
Le corps est différent de la première requête409, 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.

D'une requête à une enquête et au support

Sur cette page