GuidesOneMux

Diagnostiquer en toute sécurité les erreurs d’authentification, de limite de débit, de délai d’attente et de réponse malformée de l’API OpenAI

Guide pratique et respectueux de la confidentialité pour diagnostiquer les erreurs d’authentification, de limitation, de délai d’attente et de réponse malformée de l’API OpenAI, sans exposer d’identifiants ni de données utilisateur.

AI

Résumé · TL;DR

Pour résoudre les échecs de l’API OpenAI en toute sécurité, commencez par déterminer leur catégorie avant de réessayer. Les erreurs d’authentification nécessitent généralement de corriger une clé, une organisation, un projet ou une configuration IP ; les erreurs de débit et de quota exigent de ralentir les requêtes ou de modifier des paramètres administratifs ; les délais d’attente peuvent être temporaires ; et les réponses malformées doivent être isolées comme problèmes de transport, de proxy ou d’analyse. Consignez des métadonnées de diagnostic, pas des identifiants ni le contenu brut des utilisateurs.

Points clés

  • Ne réessayez pas les erreurs d’authentification 401 ni les erreurs de facturation ou de quota comme s’il s’agissait de problèmes réseau temporaires.
  • Pour les réponses 429 de limitation et les réponses 503 de surcharge, respectez l’en-tête Retry-After lorsqu’il est présent et appliquez un délai exponentiel avec un nombre de tentatives limité.
  • Ne stockez pas les clés API dans le code source, les journaux, les messages d’exception ni les applications côté client.
  • Traitez une réponse qui n’est pas au format JSON ou un échec d’analyse JSON comme un problème distinct de transport ou de proxy ; ne recueillez qu’un diagnostic expurgé et de longueur limitée.
  • Pour signaler un problème persistant, indiquez le modèle, le code d’erreur, l’horodatage, le fuseau horaire et les détails de la requête après les avoir assainis.
Sur cette page (7)

Les échecs de l’API OpenAI sont plus faciles à résoudre lorsqu’on distingue les erreurs de configuration, les problèmes de capacité, les défaillances réseau et les erreurs d’analyse de réponse. La première question à se poser est : un nouvel essai a-t-il des chances de changer le résultat ?

Une erreur 401 ne disparaîtra généralement pas après une nouvelle tentative. Une erreur 429 due à la cadence des requêtes peut être résolue en les espaçant, tandis qu’une erreur 429 due à l’épuisement des crédits ou à une limite de dépenses nécessite une modification du compte ou du projet. Un délai d’attente peut être temporaire, mais des délais répétés peuvent indiquer un problème de réseau, de proxy ou de taille de requête.

Les procédures ci-dessous utilisent JavaScript et les concepts de la bibliothèque officielle OpenAI décrits dans le guide des codes d’erreur OpenAI. Le code illustre une approche ; il ne s’agit pas d’une intégration de production testée.

Avant le débogage : protéger les identifiants et les données utilisateur

Avant de reproduire une erreur, prenez les précautions suivantes :

  • Stockez la clé API dans un gestionnaire de secrets côté serveur ou dans une variable d’environnement. Ne l’intégrez jamais au code d’un navigateur, d’une application mobile ou d’un dépôt de code source, et ne la joignez pas à un ticket d’assistance.
  • Consignez l’horodatage de la requête, la catégorie de point de terminaison, l’identifiant du modèle, le statut HTTP et, si disponible, le code d’erreur structuré.
  • Ne consignez pas les en-têtes Authorization, les corps complets des requêtes, les corps bruts des réponses ni les prompts contenant des données personnelles.
  • Si un prompt est nécessaire au diagnostic, consignez un exemple expurgé ou un identifiant de requête interne stable plutôt que le texte d’origine.
  • Limitez la taille des données de diagnostic. Un proxy peut renvoyer une page d’erreur HTML volumineuse, et une erreur en amont peut contenir des données que vous ne souhaitiez pas conserver.

Une bonne règle opérationnelle consiste à faire en sorte que les journaux indiquent ce qui a échoué et où, sans enregistrer ce que l’utilisateur a dit ni les moyens utilisés pour s’authentifier.

Commencer par diagnostiquer les erreurs d’authentification 401

Les cas d’erreur 401 documentés comprennent l’authentification invalide, une clé API incorrecte, l’absence d’appartenance à une organisation et une adresse IP non autorisée. Une erreur 403 peut indiquer que le pays, la région ou le territoire n’est pas pris en charge.

Vérifiez les éléments suivants dans l’ordre :

  1. Confirmez que le serveur lit le secret prévu et que celui-ci n’a pas été tronqué, expiré, révoqué ou remplacé.
  2. Confirmez que la requête est envoyée au point de terminaison API et au projet prévus.
  3. Si votre configuration utilise un identifiant d’organisation ou une liste d’adresses IP autorisées, vérifiez les deux dans la configuration du projet.
  4. Vérifiez si la requête provient d’une adresse IP de sortie différente en développement, dans un conteneur ou dans un environnement hébergé.
  5. Supprimez toute valeur d’identifiant des sorties de débogage avant de partager les journaux.

N’utilisez pas de tentatives automatiques pour les erreurs 401 ou 403. Réessayer avec le même identifiant invalide peut générer du bruit et compliquer l’analyse de l’incident. Corrigez la configuration, puis envoyez une nouvelle requête.

Distinguer la limitation 429 des erreurs de quota et de facturation

Toutes les erreurs 429 ne signifient pas « réessayez bientôt ». Le guide OpenAI distingue plusieurs cas :

Catégorie d’échecAction probableNouvelle tentative automatique ?
Limite de débit atteinteEspacer les requêtes et respecter Retry-After lorsqu’il est présentOui, avec des limites
slow_downRéduire la cadence des requêtes et l’augmenter progressivementOui, avec prudence
Solde de crédits épuiséAjouter des créditsNon
Limite de dépenses de l’organisation ou du projetModifier la limite concernéeNon
Limite d’utilisation de l’organisationDemander une limite approuvée plus élevée ou contacter l’assistanceNon

Une boucle de nouvelle tentative doit examiner le statut HTTP et le code d’erreur précis, plutôt que de traiter toutes les erreurs 429 de la même façon. Fixez un nombre maximal de tentatives, appliquez un délai exponentiel et ajoutez une variation aléatoire afin que plusieurs processus ne réessaient pas en même temps. Si Retry-After est présent, privilégiez le délai indiqué, sous réserve de votre propre attente maximale.

Tenez également compte des réponses 503. La documentation source identifie la surcharge du modèle par le code server_is_overloaded et recommande de respecter Retry-After lorsqu’il est présent avant de réessayer. Dans la bibliothèque Python, une surcharge peut être représentée par InternalServerError, tandis que les réponses 429 utilisent RateLimitError ; les gestionnaires ne doivent donc pas supposer qu’une surcharge se présente toujours sous la forme d’une erreur 429.

Examiner les délais d’attente et les problèmes de connexion

La bibliothèque Python officielle documente APITimeoutError pour les requêtes qui expirent et APIConnectionError pour les problèmes de connexion. Voici les principaux points à examiner :

  • Délai d’attente avant toute réponse : vérifiez les paramètres de délai d’attente du client, les itinéraires réseau, les proxys, les pare-feu et la taille de la requête.
  • Échec de connexion : vérifiez le DNS, les certificats TLS, les règles de pare-feu sortant et la configuration du proxy.
  • Échecs répétés côté serveur : consultez la page d’état du service et conservez des horodatages assainis pour l’assistance.

Un délai d’attente ne prouve pas que le serveur n’a pas traité la requête. Lorsque les doublons posent problème, concevez l’application de façon à pouvoir rapprocher une nouvelle tentative du traitement initial — par exemple, en associant l’opération à un enregistrement de requête propre à votre système. Ne cherchez pas à résoudre les délais d’attente en les augmentant indéfiniment ou en réessayant sans limite.

Gérer les réponses malformées sans exposer le contenu

L’expression « réponse malformée » peut désigner plusieurs problèmes : une requête invalide qui entraîne une erreur BadRequestError, une réponse qui ne respecte pas le schéma attendu, ou un proxy qui renvoie du HTML ou des données tronquées au lieu de JSON. Le guide OpenAI décrit BadRequestError comme une requête malformée ou incomplète et recommande de vérifier les paramètres requis, l’encodage, le format et la taille.

Pour les clients HTTP bruts ou les intergiciels, procédez à ces vérifications séparément :

  1. Vérifiez le statut HTTP et le Content-Type avant l’analyse.
  2. Effectuez l’analyse JSON dans un bloc de gestion des erreurs.
  3. Vérifiez la présence des champs requis avant de les utiliser.
  4. Ne consignez que le statut, le type de contenu, la longueur de la réponse et, si les règles l’autorisent, un extrait expurgé et de longueur limitée.
  5. N’incluez jamais la clé API, le prompt complet ni la réponse complète dans un message d’erreur d’analyse.

Voici à quoi pourrait ressembler un exemple de wrapper :

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

Cet exemple exclut volontairement le corps de l’erreur levée. En production, ajoutez une validation de schéma adaptée au point de terminaison et ne conservez les données brutes que dans le cadre d’un processus de diagnostic contrôlé et évalué au regard de la confidentialité.

Modèle de gestion des erreurs respectueux de la confidentialité

L’exemple JavaScript officiel distingue les erreurs de connexion, les erreurs de limitation de débit et les erreurs API plus générales. Vous pouvez compléter cette approche en classant les erreurs sans afficher de secrets ni de données utilisateur :

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

Vérifiez les noms de classes et le comportement des points de terminaison en fonction de la version du SDK que vous déployez. Ne supposez pas que tous les points de terminaison compatibles avec les fournisseurs prennent en charge chaque paramètre ou champ de réponse du SDK.

Quand faire remonter un problème

Pour les échecs persistants, le guide OpenAI recommande de fournir le modèle, le message et le code d’erreur, les données et les en-têtes de la requête, l’horodatage, le fuseau horaire et tout autre détail pertinent. Assainissez ces informations avant de les transmettre : remplacez les identifiants, supprimez les cookies, expurgez les données personnelles et résumez autant que possible le corps de la requête. Ne publiez jamais d’informations sensibles sur un forum public.

La règle pratique est simple : corrigez les problèmes d’authentification et de quota ; ralentissez les requêtes en cas de limitation ou de surcharge ; examinez les points de passage réseau en cas de délai d’attente ; et isolez les erreurs d’analyse sans conserver de données privées.

FAQ

Faut-il réessayer toutes les réponses 429 de l’API OpenAI ?

Non. Réessayez avec prudence les erreurs liées à la cadence des requêtes et les réponses `slow_down`, en appliquant un délai exponentiel et en respectant `Retry-After` lorsqu’il est présent. Les nouvelles tentatives ne résoudront pas l’épuisement des crédits ni les limites de dépenses ou d’utilisation de l’organisation.

Pourquoi une erreur de surcharge OpenAI peut-elle apparaître en 503 plutôt qu’en 429 ?

Le guide des erreurs OpenAI documente la surcharge du modèle comme une réponse 503 assortie du code `server_is_overloaded`. Les gestionnaires d’erreurs doivent examiner à la fois le statut et le code, plutôt que de supposer qu’une surcharge est toujours une réponse de limitation de débit.

Que faut-il consigner en cas d’échec d’authentification de l’API OpenAI ?

Consignez l’horodatage, l’environnement, la catégorie de point de terminaison, le statut et le code d’erreur assaini. Ne consignez pas la clé API, l’en-tête `Authorization`, le corps complet de la requête ni le prompt brut de l’utilisateur.

Comment diagnostiquer une réponse JSON invalide ?

Vérifiez le statut HTTP et le `Content-Type` avant l’analyse, ne recueillez qu’un diagnostic expurgé et de longueur limitée si les règles l’autorisent, puis examinez les proxys ou intergiciels susceptibles de renvoyer du HTML, de tronquer les données ou de modifier la réponse.

Articles liés