Passer au contenu principal
La gestion des erreurs CometAPI est plus simple lorsque vous distinguez les problèmes de requête, les problèmes d’authentification et les problèmes de plateforme réessayables. Cette page constitue le guide de référence des erreurs CometAPI et se concentre d’abord sur ce que vous pouvez vérifier côté client.
Ce guide s’appuie sur des vérifications en conditions réelles avec l’API CometAPI actuelle. Nous avons vérifié directement les erreurs 400, 401 et les échecs liés au chemin/base URL. Nous n’avons pas reproduit les erreurs 413, 429, 500, 503, 504 ou 524 dans des tests limités, donc les recommandations pour ces statuts sont volontairement prudentes.

​
Diagnostic rapide

StatusCe que cela signifie généralementRéessayer ?Première action
400La validation de la requête a échoué avant que celle-ci ne soit correctement acheminée.NonValidez model, messages, la structure JSON et les types de champs.
401La clé API est absente, mal formée ou invalide.NonVérifiez Authorization: Bearer <COMETAPI_KEY>.
403L’accès a été bloqué ou la requête actuelle n’était pas autorisée.Généralement nonRéessayez avec une requête connue comme valide et retirez d’abord les champs spécifiques au modèle.
Path mistakeMauvaise base URL ou mauvais chemin d’endpoint. Sur Comet, cela peut apparaître sous forme de redirection 301 ou de HTML, et non d’un 404 JSON propre.NonUtilisez exactement https://api.cometapi.com/v1 et désactivez le suivi automatique des redirections pendant le débogage.
429Limitation de débit ou saturation temporaire.OuiUtilisez un backoff exponentiel avec jitter.
500, 503, 504, 524Échec de plateforme ou lié à un timeout.OuiRéessayez avec backoff et conservez l’identifiant de requête.

​
Enveloppe d’erreur

L’enveloppe d’erreur JSON actuellement renvoyée par CometAPI ressemble à ceci : 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
De nombreux messages d’erreur observés en conditions réelles incluent également un request id dans error.message. Conservez cette valeur lorsque vous avez besoin d’assistance.

​
400 Bad Request

Voici ce que nous avons observé avec l’API en conditions réelles lorsque model était omis : 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
En pratique, 400 signifie généralement que le corps de la requête a échoué à la validation avant que la plateforme puisse l’acheminer vers le fournisseur de modèle. Causes fréquentes :
  • Champs obligatoires manquants, tels que model ou messages
  • Structure JSON invalide
  • Envoi d’un champ avec un type incorrect
  • Réutilisation de paramètres spécifiques à un fournisseur que l’endpoint sélectionné n’accepte pas
Que faire :
  1. Partez d’une requête minimale connue comme valide.
  2. Rajoutez les champs facultatifs un par un.
  3. Comparez le corps de la requête au schéma de l’endpoint dans la référence d’API.
Exemple minimal connu comme valide : 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Remplacez your-model-id par n’importe quel ID de modèle actuel depuis la page des modèles CometAPI.

​
401 Invalid Token

Voici ce que nous avons observé avec l’API en conditions réelles avec une clé invalide : 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
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

Nous n’avons pas reproduit de 403 stable dans des tests limités, évitez donc de considérer un ancien modèle de message isolé comme l’explication complète. Dans la documentation Comet actuelle, 403 est le plus souvent évoqué dans 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 pour fonctionner.
  2. Supprimez les champs avancés et les paramètres spécifiques au provider, 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 comme group ou channel, considérez-les comme des détails de routage, pas comme le premier élément à diagnostiquer côté client. En pratique, la bonne approche reste de valider d’abord le token, le modèle et la forme de la requête.

​
Mauvaise base URL ou mauvais chemin

C’est la partie où l’ancienne page était la moins exacte. Lors de vérifications en conditions réelles sur les endpoints Comet actuels :
  • Un envoi vers https://api.cometapi.com/chat/completions a renvoyé une redirection 301 vers https://www.cometapi.com/chat/completions
  • Un envoi vers une fausse route API comme https://api.cometapi.com/v1/not-a-real-endpoint a également renvoyé une redirection 301 vers https://www.cometapi.com/v1/not-a-real-endpoint
Cela signifie qu’une erreur de chemin peut se manifester par :
  • Une redirection
  • Une réponse HTML non-JSON si votre client suit les redirections
  • Une erreur de parsing dans votre SDK
  • Une requête qui n’atteint jamais proprement la couche API
Utilisez exactement cette base URL : 
https://api.cometapi.com/v1
Vérifications recommandées :
  1. Confirmez que la base URL 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

Nous n’avons pas reproduit de 413 dans un test limité, même avec un corps de requête JSON surdimensionné de 8 MiB, donc l’ancienne explication selon laquelle le prompt était trop long était trop restrictive. Si vous voyez bien un 413, considérez d’abord qu’il s’agit d’un problème de taille de requête. Les suspects courants sont :
  • De gros payloads 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. Fractionnez les gros traitements en requêtes plus petites.
  3. Ne supposez pas que seule la longueur du texte brut en soit la cause.

​
429 Too Many Requests

Nous n’avons pas reproduit de 429 lors d’un test limité de concurrence avec 24 requêtes parallèles GET /v1/models, donc le seuil exact dépend clairement de la route, du modèle et de l’état actuel de la plateforme. Considérez 429 comme réessayable :
  1. Utilisez un backoff exponentiel avec jitter.
  2. Réduisez la concurrence en rafale.
  3. Gardez 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 sur Chat Completions.

​
500, 503, 504, et 524

Nous n’avons pas reproduit ces statuts dans des tests limités. Ils doivent être documentés comme des échecs côté serveur ou de type timeout, et non comme des erreurs de l’utilisateur. Guide pratique :
  • 500 : échec interne de la plateforme ou côté provider
  • 503 : route ou service provider temporairement indisponible
  • 504 et 524 : échecs de type timeout entre la plateforme, l’edge ou le service provider
Que faire :
  1. Réessayez avec 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
  • Nom du modèle
  • JSON du corps de requête anonymisé (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 :
  • Les noms de champ et les valeurs texte que vous avez envoyés avec le fichier
  • Le nom du fichier, son type et sa taille approximative
  • Si le fichier a été uploadé directement, référencé par URL ou intégré en base64
Le moyen le plus rapide de reproduire un bug est de disposer de la charge utile exacte de la requête anonymisé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.