Skip to main content
La gestion des erreurs CometAPI est plus simple lorsque vous distinguez les problèmes de structure de requête, les problèmes d’authentification, les erreurs de chemin, et les défaillances de plateforme réessayables. Utilisez la combinaison du statut HTTP, de error.code et de error.message pour décider s’il faut corriger la requête ou la relancer.

​
Triage rapide

​
Enveloppe d’erreur

De nombreux échecs CometAPI utilisent un corps d’erreur comme celui-ci :
Certaines réponses laissent code vide. Lorsque le statut est 500, considérez error.code et error.message comme le signal décisif.

​
400 Bad Request

Un 400 signifie généralement que le corps de la requête a échoué à la validation avant que la requête ne puisse être traitée normalement. Causes courantes :
  • Champs obligatoires manquants, comme model
  • Structure JSON invalide
  • Envoi d’un champ avec un mauvais type
  • Réutilisation de paramètres spécifiques à un fournisseur que l’endpoint sélectionné n’accepte pas
Partez d’une requête minimale connue comme valide, puis rajoutez les champs optionnels un par un. Comparez la charge utile au schéma de l’endpoint dans la documentation de référence de l’API. Utilisez une requête minimale comme celle-ci :
Remplacez your-model-id par n’importe quel model ID actuel depuis la page des modèles CometAPI. Ne supposez pas que toutes les requêtes chat mal formées renvoient 400. Des champs chat obligatoires manquants, comme messages, peuvent aussi se manifester sous la forme d’un 500 avec error.code: invalid_request.

​
500 Internal Server Error

La plupart des réponses 500 indiquent une défaillance de plateforme ou de fournisseur. Pour Chat Completions, certaines requêtes mal formées peuvent aussi apparaître comme des 500 tout en contenant error.code: invalid_request. Un exemple est une requête qui omet messages :
Si une réponse 500 contient error.code: invalid_request, traitez-la comme un problème de requête :
  1. Corrigez le corps de la requête.
  2. Comparez la charge utile au schéma de l’endpoint.
  3. Réessayez uniquement après avoir corrigé la charge utile.
Si une réponse 500 n’indique pas une requête invalide, conservez le request id et utilisez un backoff.

​
401 Invalid Token

Un échec de token ressemble généralement à ceci :
Points à vérifier :
  1. L’en-tête doit être exactement Authorization: Bearer $COMETAPI_KEY.
  2. Assurez-vous que votre application ne charge pas une ancienne clé depuis .env, l’historique du shell ou un gestionnaire de secrets déployé.
  3. Si une clé échoue et qu’une autre fonctionne sur la même requête, traitez cela comme un problème de token, et non comme un problème d’endpoint.

​
403 Forbidden

403 correspond le plus souvent à l’une de ces situations :
  • La requête est bloquée par une règle côté plateforme, comme un filtrage WAF
  • Le token ou la route n’est pas autorisé à utiliser le modèle demandé ou la forme de requête demandée
  • Le modèle choisi rejette l’un des paramètres avancés que vous avez transmis
Que faire en premier :
  1. Réessayez avec une requête texte très simple sur un modèle connu comme fonctionnel.
  2. Supprimez les champs avancés et les paramètres spécifiques au fournisseur, puis rajoutez-les progressivement.
  3. Si la réponse inclut un request id, conservez-le avant de contacter le support.
Si le message mentionne des termes internes tels que group ou channel, considérez-les comme des détails de routage, et non comme la première chose à diagnostiquer côté client. La solution pratique consiste toujours à valider d’abord le token, le modèle et la forme de la requête.

​
URL de base erronée ou mauvais chemin

Sur Comet, une erreur de chemin peut se manifester par :
  • Une redirection
  • Une réponse HTML non JSON si votre client suit les redirections
  • Une erreur d’analyse dans votre SDK
  • Une requête qui n’atteint jamais proprement la couche API
Utilisez exactement cette URL de base :
Vérifications recommandées :
  1. Confirmez que l’URL de base inclut /v1.
  2. Confirmez que le chemin de l’endpoint correspond exactement à la documentation.
  3. Désactivez le suivi automatique des redirections pendant le débogage des problèmes de chemin.

​
413 Request Entity Too Large

Si vous voyez 413, considérez d’abord qu’il s’agit d’un problème de taille de requête. Les causes courantes sont :
  • De grosses charges utiles base64
  • Des images ou fichiers audio trop volumineux intégrés inline
  • Des corps multipart ou JSON très volumineux
Que faire :
  1. Réduisez ou compressez le contenu joint.
  2. Divisez les tâches volumineuses en requêtes plus petites.
  3. Ne supposez pas que la longueur du texte brut est la seule cause possible.

​
429 Too Many Requests

Traitez 429 comme une erreur réessayable :
  1. Utilisez un backoff exponentiel avec jitter.
  2. Réduisez la concurrence en rafale.
  3. Laissez la journalisation des requêtes activée afin de voir quelle route et quel modèle saturent en premier.
Pour un modèle de retry réutilisable, consultez l’exemple de backoff dans Chat Completions.

​
503, 504, and 524

Ces statuts sont des échecs côté serveur ou liés aux délais d’attente. Conseils pratiques :
  • 503 : route ou service du fournisseur temporairement indisponible
  • 504 et 524 : échecs liés aux délais d’attente entre la plateforme, la périphérie réseau ou le service du fournisseur
Que faire :
  1. Réessayez avec un backoff.
  2. Conservez le request id, l’endpoint, le modèle et l’horodatage.
  3. Si le même échec se répète sur plusieurs tentatives, contactez le support avec ce contexte.

​
Avant de contacter le support

Commencez par rassembler ces informations :
  • Méthode HTTP
  • Chemin de l’endpoint
  • model ID
  • JSON du corps de requête nettoyé (c’est l’élément le plus utile pour la plupart des appels API)
  • Paramètres de requête si la requête en échec les utilisait
  • Corps de réponse exact si votre client l’a capturé
  • Statut HTTP complet
  • Le error.message exact
  • Tout request id
  • Horodatage approximatif
  • Si la même requête fonctionne avec un autre modèle ou un autre token
Si la route en échec accepte des uploads de fichiers (édition d’image, upload audio, génération vidéo, etc.) au lieu d’un simple corps JSON, envoyez la charge utile soumise équivalente :
  • Noms des champs et valeurs textuelles que vous avez envoyés avec le fichier
  • Nom du fichier, type de fichier et taille approximative du fichier
  • Si le fichier a été téléversé directement, référencé par URL ou intégré en base64
La manière la plus efficace de reproduire un bug est de disposer de la charge utile exacte de la requête nettoyée. Pour la plupart des appels API, cela signifie le JSON brut du corps de requête. Pour les routes avec upload de fichiers, cela signifie la liste des champs plus les métadonnées du fichier.
Cela réduit considérablement le délai de traitement du support.