Codes d’erreur et gestion - CometAPI Documentation

La gestion des erreurs CometAPI est plus simple lorsque vous distinguez les problèmes de structure de requête, les problèmes d’auth, les erreurs de chemin, et les défaillances temporaires de la plateforme pouvant faire l’objet d’une nouvelle tentative. 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 retenter.

Triage rapide

Status	Ce que cela signifie généralement	Retry?	Première action
`400`	La validation de la requête a échoué avant que la requête ne soit traitée normalement.	Non	Validez `model`, `messages`, la structure JSON et les types des champs.
`401`	La clé API est absente, mal formée ou invalide.	Non	Vérifiez `Authorization: Bearer <COMETAPI_KEY>`.
`403`	L’accès a été bloqué ou la requête actuelle n’était pas autorisée.	Généralement non	Réessayez avec une requête connue comme valide et supprimez d’abord les champs spécifiques au modèle.
Path mistake	URL de base incorrecte ou mauvais chemin d’endpoint. Sur Comet, cela peut apparaître sous la forme d’une redirection `301` ou de HTML, et non d’un `404` JSON propre.	Non	Utilisez exactement `https://api.cometapi.com/v1` et désactivez le suivi automatique des redirections pendant le débogage.
`429`	Limitation de débit ou saturation temporaire.	Oui	Utilisez un backoff exponentiel avec jitter.
`500` with `error.code: invalid_request`	Une requête mal formée a remonté via une réponse de statut serveur.	Non	Corrigez le corps de la requête avant de réessayer.
`500`, `503`, `504`, `524`	Défaillance de plateforme, de fournisseur ou liée à un délai d’expiration.	Oui	Réessayez avec un backoff et conservez le request id.

Enveloppe d’erreur

De nombreux échecs CometAPI utilisent un corps d’erreur comme celui-ci :

{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}

Certaines réponses laissent code vide. Lorsque le statut est 500, considérez error.code et error.message comme le signal déterminant.

`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 puisse être traitée normalement. Causes fréquentes :

Champs obligatoires manquants, comme model
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

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 référence API. Utilisez une requête minimale comme celle-ci :

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Remplacez your-model-id par n’importe quel model ID actuel depuis la page des modèles CometAPI. Ne supposez pas que chaque requête de chat mal formée renvoie 400. Des champs de chat obligatoires manquants, comme messages, peuvent aussi remonter sous forme de 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 également remonter comme des 500 tout en contenant error.code: invalid_request. Un exemple est une requête qui omet messages :

{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}

Si une réponse 500 contient error.code: invalid_request, traitez-la comme un problème de requête :

Corrigez le corps de la requête.
Comparez la charge utile au schéma de l’endpoint.
Ne réessayez qu’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 :

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

Points à vérifier :

L’en-tête doit être exactement Authorization: Bearer <COMETAPI_KEY>.
Assurez-vous que votre application ne charge pas une ancienne clé depuis .env, l’historique du shell ou un magasin de secrets déployé.
Si une clé échoue et qu’une autre fonctionne pour 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 model demandé ou la forme de requête demandée
Le model choisi rejette l’un des paramètres avancés que vous avez transmis

Que faire en premier :

Réessayez avec une requête texte très simple sur un model connu pour fonctionner.
Supprimez les champs avancés et les paramètres spécifiques au fournisseur, puis rajoutez-les progressivement.
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, traitez-les comme des détails de routage, et non comme le premier élément à diagnostiquer côté client. La correction pratique consiste toujours à valider d’abord le token, le model et la forme de la requête.

Mauvaise base URL 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 base URL :

https://api.cometapi.com/v1

Vérifications recommandées :

Confirmez que la base URL inclut /v1.
Confirmez que le chemin de l’endpoint correspond exactement à la documentation.
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, traitez-le d’abord comme un problème de taille de requête. Les causes courantes sont :

De grosses charges utiles base64
Des images ou des fichiers audio surdimensionnés intégrés en ligne
Des corps multipart ou JSON très volumineux

Que faire :

Réduisez ou compressez le contenu joint.
Découpez les tâches volumineuses en requêtes plus petites.
Ne partez pas du principe que la longueur du texte brut est la seule cause.

`429 Too Many Requests`

Considérez 429 comme réessayable :

Utilisez un backoff exponentiel avec jitter.
Réduisez la concurrence en rafale.
Conservez la journalisation des requêtes activée afin de voir quelle route et quel model saturent en premier.

Pour un modèle de retry réutilisable, consultez l’exemple de backoff sur Chat Completions.

`503`, `504`, et `524`

Ces statuts correspondent à des échecs côté serveur ou de type timeout. Conseils pratiques :

503 : route ou service fournisseur temporairement indisponible
504 et 524 : échecs de type timeout entre la plateforme, l’edge ou le service fournisseur

Que faire :

Réessayez avec un backoff.
Conservez le request id, l’endpoint, le model et l’horodatage.
Si le même échec se répète après plusieurs tentatives, contactez le support avec ce contexte.

Avant de contacter le support

Capturez d’abord ces informations :

Méthode HTTP
Chemin de l’endpoint
Model ID
JSON du corps de requête anonymisé (c’est l’élément le plus utile, et de loin, 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 de vidéo, etc.) au lieu d’un simple corps JSON, envoyez la charge utile soumise équivalente :

Noms des champs et valeurs de texte que vous avez envoyés avec le fichier
Nom du fichier, type de fichier et taille approximative du fichier
Indiquez si le fichier a été uploadé directement, référencé par URL ou intégré en base64

Le moyen le plus efficace de reproduire un bug est 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 fichier, 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.

Documentation Index

​Triage rapide

​Enveloppe d’erreur

​400 Bad Request

​500 Internal Server Error

​401 Invalid Token

​403 Forbidden

​Mauvaise base URL ou mauvais chemin

​413 Request Entity Too Large

​429 Too Many Requests

​503, 504, et 524

​Avant de contacter le support

Triage rapide

Enveloppe d’erreur

`400 Bad Request`

`500 Internal Server Error`

`401 Invalid Token`

`403 Forbidden`

Mauvaise base URL ou mauvais chemin

`413 Request Entity Too Large`

`429 Too Many Requests`

`503`, `504`, et `524`

Avant de contacter le support