Guides essentiels
Gérer les erreurs de l'API
Lisez les codes d'erreur, réessayez uniquement lorsque cela est utile et conservez le Request ID
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 avec 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 | Modifiez les permissions de la clé ou le modèle |
404 | La ressource n'existe pas ou n'est plus disponible | Vérifiez l'ID et la clé API qui l'a créé |
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 de l'endpoint |
429 | Limite de requêtes atteinte | Attendez selon Retry-After |
500–504 | Service indisponible ou erreur réseau | Réessayez uniquement si retryable vaut true ; respectez retry_after et limitez les tentatives |
Codes d'erreur courants
| Code | Signification | Que modifier |
|---|---|---|
invalid_api_key | La clé API est absente, invalide, inactive ou révoquée | Vérifiez l'en-tête Authorization et la valeur de la clé |
expired_api_key | La clé API 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é |
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 large |
rate_limit_exceeded | Trop de requêtes ont été envoyées dans la fenêtre actuelle | Attendez selon Retry-After |
payload_too_large | Le corps de la requête ou le fichier dépasse la limite de l'endpoint | Réduisez ou compressez l'entrée |
all_channels_failed | Le modèle sélectionné ne peut pas traiter cette requête | Réessayez uniquement si retryable vaut true ; respectez retry_after et limitez les tentatives |
timeout_error | La requête n'a pas abouti à temps | Réessayez uniquement lorsque l'opération peut être répétée en toute sécurité |
503 all_channels_failed ou 503 delivery_tier_unavailable ne signifie pas toujours une panne temporaire. Si aucune offre ne couvre cette opération dans le niveau Delivery choisi, retryable vaut false et retry_after est absent. Ne répétez pas la même requête. Vérifiez la disponibilité de l’opération et du niveau Delivery avec GET /v1/models avant de choisir un autre modèle. Des noms similaires ne prouvent pas la disponibilité ; les alternatives non vérifiées sont omises.
Certaines erreurs compatibles avec OpenAI incluent des champs optionnels did_you_mean, suggestions, alternatives, hint, retryable ou retry_after. Voir Erreurs sur lesquelles les agents peuvent agir.
Lorsqu'une requête est passée par une route Official et que le service en amont a rejeté la requête elle-même, par exemple pour une entrée qu'il n'accepte pas ou une décision de politique de contenu, l'erreur contient aussi upstream : le message du service en amont tel qu'il l'a renvoyé, ainsi que code et source (le nom du service en amont) lorsqu'ils sont connus. Les erreurs Anthropic Messages et Gemini contiennent le même objet dans leur propre error. Continuez à vous baser sur code et type ; les valeurs de 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 si retryable vaut true ; respectez retry_after et limitez les tentatives |
| Connexion fermée avant toute réponse | Parfois. Pour les opérations de création, vérifiez 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. Répéter 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 Worlds, enregistrez l'ID de tâche dès qu'il est renvoyé. Si une requête de création expire, vérifiez l'enregistrement de la tâche avant d'envoyer une autre requête de création.
Conservez le Request ID
Les en-têtes de réponse incluent un Request ID pour le traçage. Enregistrez-le avec l'endpoint, 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'URLs signées ou de prompts privés complets.