Codes d’erreur et gestion

Résolvez les échecs de requêtes CometAPI grâce à des conseils vérifiés pour les erreurs 400, 401 et de chemin, ainsi qu’une gestion pratique des échecs 403, 429 et liés aux timeouts.

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

Status	Ce que cela signifie généralement	Réessayer ?	Première action
400	La validation de la requête a échoué avant que celle-ci ne soit correctement acheminée.	Non	Validez model, messages, la structure JSON et les types de 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 retirez d’abord les champs spécifiques au modèle.
Path mistake	Mauvaise 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.	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, 503, 504, 524	Échec de plateforme ou lié à un timeout.	Oui	Ré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.