Codes d’erreur et dépannage

Identifier la défaillance

1. Consignez le statut HTTP réel, la méthode et le chemin de requête. Le statut HTTP et le code d’erreur applicatif décrivent des couches différentes ; ne les substituez pas l’un à l’autre.
2. Lisez les champs d’erreur selon le protocole appelé. Les réponses natives, OpenAI, Claude et Gemini n’ont pas toutes la même structure.
3. Pour le streaming, examinez aussi les événements d’erreur et l’état de fin. Pour les tâches asynchrones, examinez leur status. HTTP 200 ne garantit pas une génération réussie.
4. Utilisez le tableau ci-dessous pour corriger la requête ou décider d’une nouvelle tentative. message est un texte explicatif, pas une énumération stable ; ne conditionnez pas votre logique à sa formulation.

Énumération des codes d’erreur de plateforme

Voici l’énumération complète des codes d’erreur applicatifs de la plateforme. Les noms sont des libellés de référence ; les valeurs code des réponses sont numériques. « HTTP courant » est un guide de dépannage, pas une correspondance fixe pour chaque endpoint. Utilisez le statut HTTP et le corps réels. Un code transmis depuis le fournisseur peut ne pas appartenir à cette énumération.

HTTP 429 seul ne distingue pas fiablement une limite de débit d’une limite de concurrence. Faites cette distinction uniquement avec un code numérique explicite. Vérifiez les identifiants dans la liste des modèles ; ne réécrivez pas vous-même les valeurs de model.

Lire les erreurs selon le protocole

Les exemples ci-dessous montrent des structures courantes générées par la plateforme, pas un format unique garanti pour tous les échecs. L’authentification peut échouer à différentes couches, et les réponses transmises du fournisseur peuvent conserver leurs structures, codes textuels ou types. Identifiez la structure réelle avant de l’analyser. Si elle est inconnue, conservez les champs d’origine et le statut HTTP plutôt que de forcer une conversion.

API natives de la plateforme

Lisez généralement error.code et error.message. requestId peut être absent.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Certaines erreurs peuvent utiliser code et message de premier niveau. Les clients doivent tolérer cette différence et ne pas considérer l’absence d’objet error comme preuve de réussite. Les réponses de validation peuvent aussi ne pas avoir de code numérique. Traitez un code absent comme inconnu, sans l’inventer.

API compatibles OpenAI

Les erreurs courantes générées par la plateforme utilisent code, message et type de premier niveau ; elles ne sont pas nécessairement enveloppées dans error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type est une catégorie de protocole ; code est le code numérique de plateforme dans cette structure. api_error seul ne détermine pas si une nouvelle tentative est appropriée. Les erreurs transmises du fournisseur ou du streaming peuvent contenir un error imbriqué ; traitez la réponse réelle du protocole. Consultez Chat Completions et Responses.

API compatibles Claude

Dans la structure courante, le type de premier niveau vaut error, la catégorie précise est error.type et la description est error.message. Cette structure n’inclut pas de code numérique de plateforme. N’en inventez pas.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

La plateforme génère localement les types d’erreur Claude suivants. Ce n’est pas une énumération exhaustive des types d’erreur fournisseur.

Consultez Claude Messages.

Erreurs au format Gemini

Lorsque vous recevez une réponse au format Gemini, lisez error.code, error.message et error.status. Ici, status est une catégorie textuelle, pas un statut HTTP ou de tâche asynchrone.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Les erreurs de plateforme de cette structure utilisent des valeurs code numériques de plateforme. La correspondance locale de status est ci-dessous ; elle n’énumère pas tous les états fournisseur.

503 est prioritaire et utilise UNAVAILABLE, pas INTERNAL. Les réponses fournisseur peuvent donner d’autres sens à code et status. N’appliquez pas le tableau des codes de plateforme à tous les codes numériques Gemini.

Relancer prudemment

Respectez un en-tête Retry-After valide lorsqu’il est présent. Ne supposez pas que chaque erreur en contient un. Relancer automatiquement une génération non idempotente peut l’exécuter à nouveau et entraîner des frais supplémentaires. Cette page ne promet pas une prise en charge générale des clés d’idempotence ; ajouter vous-même Idempotency-Key ne garantit pas la déduplication.

Si vous avez déjà un jobId, interrogez cette tâche avant d’en créer une autre. Sans jobId et avec une issue incertaine, conservez l’identifiant de requête et l’horodatage pour investigation.

Flux et tâches asynchrones

Requêtes SSE

Après le début de SSE, le statut HTTP peut rester 200 alors qu’un échec ultérieur est signalé par un événement d’erreur ou des données dans le flux. Analysez les événements et données du protocole choisi et vérifiez la fin normale. En cas d’erreur ou de déconnexion inattendue, ne considérez pas du texte ou des images partielles comme un résultat complet réussi. Les noms et charges d’événements diffèrent selon l’endpoint. Ne vérifiez pas un seul champ fixe error et n’utilisez pas « du texte reçu » comme condition de réussite.

Tâches asynchrones

Une réponse de création contenant data.jobId signifie que la requête a été acceptée, pas que la génération est terminée. Une réponse HTTP réussie lors de la consultation d’une tâche indique que la consultation a réussi. Vous devez encore examiner data.status :

• PENDING, CONNECT, PROCESSING : continuez l’interrogation comme indiqué dans la documentation Jobs.
• COMPLETED : lisez outputResult.
• FAILED, CANCELLED : arrêtez l’interrogation et conservez l’ID de tâche et les informations de réponse expurgées pour investigation.

Les détails de l’échec peuvent apparaître dans data.outputResult.error. Ce champ est facultatif et n’est pas garanti pour chaque tâche échouée. Utilisez Jobs uniquement si la création renvoie explicitement un jobId. N’interrogez pas de tâche pour les endpoints renvoyant directement des résultats en JSON ou SSE.

Diagnostics pour utilisateurs et assistants d’IA

Fournissez les informations expurgées suivantes à l’assistance ou à un assistant d’IA. Utilisez unknown pour les champs absents ; utilisez unknown pour le statut HTTP si aucune réponse HTTP n’a été reçue. Conservez les chemins et types d’origine, par exemple error.code: 10000 (number) ou error.code: "invalid_api_key" (string). Ne convertissez pas automatiquement un code textuel en code numérique de plateforme et n’inventez pas les champs absents à partir de message, du statut HTTP ou des noms de modèles.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Lisez requestId dans le corps ou l’en-tête de réponse X-Request-ID lorsqu’il est disponible. Gardez jobId sous forme de chaîne pour éviter la perte de précision sur les grands nombres. Fournissez uniquement les paramètres minimaux expurgés. Retirez clés API, jetons, cookies, en-têtes complets d’authentification, données personnelles, consignes privées et contenu des fichiers d’entrée. Retirez les paramètres d’URL et les URL d’entrée ou de sortie contenant signatures ou identifiants d’accès. Ne collez pas de journaux complets sans les examiner.

Les assistants d’IA doivent distinguer les champs observés des causes possibles et identifier les informations manquantes. Des preuves insuffisantes ne permettent pas d’affirmer qu’une requête a réussi, n’a pas été exécutée ou n’a entraîné aucun frais.