For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale
Theme

Suggestions

API Agents

Agents SDK

ChatKit

Tableau de bord de l’API
Essayez ChatGPT

Erreurs et reprise

Comprenez les erreurs de l’API Agents et reprenez le travail en toute sécurité.

Pour les erreurs HTTP générales et les exceptions des SDK, consultez le guide des codes d’erreur.

Examiner une erreur

Si une requête échoue, examinez la réponse HTTP. Si l’échec survient pendant un tour ou lors de l’initialisation de l’environnement, consultez les événements et l’état enregistré.

Échec Où chercher
Requête API Consultez le code d’état HTTP et l’objet error de la réponse.
Tour À la réception de agent.session.turn.failed, récupérez le tour et examinez status et error.
Session À la réception de agent.session.failed, récupérez la session et examinez status et error.
Environnement Consultez environment.error dans agent.session.environment.failed. Voir le guide de dépannage du bac à sable.

Pour les erreurs structurées, utilisez error.code dans la logique de votre application et error.message pour expliquer l’échec. En cas d’erreur de validation d’une requête, error.param peut indiquer le champ à corriger. Prévoyez les codes inconnus et l’absence de param pour que votre gestionnaire d’erreurs continue de fonctionner.

Dans la version bêta de l’API (OpenAI-Beta: agents=v1), le champ error d’une session contient un message sous forme de chaîne de caractères ou vaut null. Consultez l’événement SSE error associé pour connaître le code d’erreur de la session.

Erreurs de requête API

Ces erreurs concernent la requête adressée à l’API Agents. Elles se distinguent des erreurs de tour renvoyées une fois le travail commencé.

Code Description
400 : invalid_request_error Cause : Une valeur d’entrée ou de configuration est invalide ou trop volumineuse.
Solution : Corrigez le champ indiqué par error.param ou error.message. Voir Corriger les données d’entrée invalides.
400 : invalid_beta Cause : L’en-tête OpenAI-Beta contient une valeur invalide.
Solution : Vérifiez l’en-tête requis par la version de l’API que vous utilisez.
400 : agent_not_persisted Cause : L’identifiant agent_id fourni appartient à un agent propre à une session.
Solution : Créez un agent enregistré et utilisez son identifiant.
400 : invalid_otlp_endpoint, invalid_otlp_header Cause : Le point de terminaison ou les en-têtes de traçage sont invalides.
Solution : Corrigez votre configuration de traçage.
401 : unauthorized ; 403 : forbidden Cause : L’authentification a échoué ou l’appelant ne dispose pas des droits d’accès nécessaires.
Solution : Consultez les consignes générales sur l’authentification et les autorisations.
404 : not_found_error, model_not_found Cause : La requête ne peut pas accéder à la ressource ou au modèle.
Solution : Vérifiez l’identifiant, le modèle et le projet. Vérifiez aussi si la ressource a été supprimée.
409 : conflict_error Cause : L’opération est incompatible avec l’état actuel de la ressource.
Solution : Lisez le message et récupérez l’état actuel avant de réessayer.
409 : executor_version_incompatible Cause : La version de l’exécuteur n’est pas prise en charge.
Solution : Mettez l’exécuteur à niveau, puis réessayez.
424 : mcp_server_startup_failed Cause : Un serveur MCP n’a pas pu démarrer.
Solution : Vérifiez la configuration et les identifiants du serveur. Voir Résoudre les problèmes de connexion.
429 : files_api_rate_limit_exceeded Cause : Les requêtes d’accès aux fichiers ont dépassé la limite de débit de l’API Files pour votre compte utilisateur.
Solution : Réduisez le nombre de requêtes simultanées et suivez les consignes relatives aux limites de débit de l’API Files.
500 : internal_error Cause : Le service a rencontré une erreur inattendue.
Solution : Vérifiez le travail enregistré avant de réessayer. Consultez les consignes générales sur les erreurs de serveur.
503 : service_unavailable_error, server_is_overloaded Cause : Le service ou l’une de ses dépendances est temporairement indisponible ou en surcharge.
Solution : Suivez les consignes générales sur les erreurs 503 et vérifiez le travail enregistré avant de réessayer.

Limites de débit de l’API Files

Les requêtes visant à créer une session ou à y joindre des fichiers peuvent renvoyer le code HTTP 429 avec files_api_rate_limit_exceeded. L’API Agents vérifie les fichiers via l’API Files. Ces vérifications sont décomptées du quota de l’utilisateur authentifié pour l’API Files. Chaque fichier joint peut nécessiter une vérification distincte.

{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

Réduisez le nombre de requêtes simultanées qui accèdent aux fichiers. Augmentez le délai d’attente de façon exponentielle entre les tentatives et limitez leur nombre. Si vous réessayez immédiatement, vous risquez de continuer à épuiser votre quota.

Cette réponse HTTP indique que l’opération a échoué. Le cas est différent lorsqu’une session ou un tour échoue de façon asynchrone après une réponse confirmant sa création. Pour détecter un dépassement de la limite de débit, vérifiez error.code plutôt que de comparer le texte du message.

Erreurs de tour

Un tour qui échoue a pour état status: "failed". Son objet error contient un champ code et un champ message. Par exemple, une surcharge du modèle peut produire l’erreur suivante :

{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

Les codes d’erreur de tour n’ont pas de code d’état HTTP propre. Par exemple, en cas de surcharge, un tour qui échoue utilise server_overloaded, tandis qu’une réponse HTTP peut utiliser server_is_overloaded.

Code Description
invalid_request Cause : Les données d’entrée ou la configuration sont invalides.
Solution : Corrigez les données d’entrée indiquées dans le message avant de réessayer.
context_length_exceeded Cause : Les données d’entrée dépassent la fenêtre de contexte du modèle.
Solution : Réduisez le volume des données d’entrée. Si la conversation est trop longue, démarrez une nouvelle session avec un résumé plus court.
session_budget_exceeded Cause : La session a épuisé son budget d’utilisation.
Solution : Démarrez une nouvelle session pour continuer.
credit_balance_exhausted Cause : L’organisation a épuisé ses crédits API.
Solution : Consultez les consignes relatives au solde de crédits.
project_spend_limit_exceeded Cause : Le projet a atteint le plafond de dépenses qui lui est imposé.
Solution : Consultez les consignes relatives au plafond de dépenses du projet.
organization_spend_limit_exceeded Cause : L’organisation a atteint le plafond de dépenses qui lui est imposé.
Solution : Consultez les consignes relatives au plafond de dépenses de l’organisation.
organization_usage_limit_exceeded Cause : L’organisation a atteint la limite d’utilisation fixée par OpenAI.
Solution : Consultez les consignes relatives à la limite d’utilisation de l’organisation.
usage_limit_exceeded Cause : Une limite de facturation ou d’utilisation a été atteinte, sans code d’erreur plus précis.
Solution : Suivez les consignes générales sur les erreurs de facturation.
rate_limit_exceeded Cause : Les requêtes ont dépassé une limite de débit applicable.
Solution : Suivez les étapes pour réessayer.
server_overloaded Cause : Le service du modèle est temporairement en surcharge.
Solution : Patientez avant de reprendre le travail inachevé. Si la surcharge persiste, changez de modèle pour les tours suivants.
flex_unavailable Cause : Le traitement Flex est temporairement indisponible.
Solution : Réessayez plus tard ou modifiez l’offre de la session pour utiliser le traitement standard (default) lors des tours suivants.
connection_failed, request_timeout, server_error, internal_error Cause : Un problème de connexion, un dépassement du délai d’attente ou une défaillance du service a interrompu le tour.
Solution : Vérifiez le travail enregistré, puis réessayez en limitant le nombre de tentatives.
authentication_error Cause : Un problème d’identifiants ou d’autorisations a empêché l’accès au modèle.
Solution : Consultez les consignes générales sur l’authentification et les autorisations.
resource_not_found Cause : Le modèle ou la ressource demandée est indisponible.
Solution : Vérifiez le modèle et la configuration de la session avant de réessayer.
sandbox_error Cause : L’environnement n’a pas pu terminer une opération.
Solution : Examinez l’erreur de l’environnement et corrigez le problème de configuration ou de connexion.
executor_version_incompatible Cause : L’exécuteur ne peut pas exécuter ce tour.
Solution : Mettez l’exécuteur à niveau, puis réessayez dans la même session si celle-ci n’a pas échoué.
active_turn_not_steerable Cause : Le tour en cours ne peut plus accepter de données d’entrée.
Solution : Attendez la fin du tour avant d’envoyer un autre message.
cyber_policy, misalignment_policy_violation Cause : Les systèmes de sécurité ont bloqué la requête.
Solution : Examinez la requête au regard des exigences de sécurité applicables avant de soumettre des données d’entrée modifiées.

Erreurs de session et d’environnement

L’échec d’un tour n’entraîne pas toujours celui de la session. Récupérez la session pour déterminer si vous pouvez la poursuivre. Si status vaut requires_action, traitez les actions requises. Si la session a échoué, corrigez la cause de l’échec et créez une nouvelle session avec les données d’entrée dont vous avez encore besoin.

Code Description
environment_connection_failed, environment_connection_timeout Cause : Le bac à sable n’a pas pu se connecter ou a mis trop de temps à établir la connexion.
Solution : Vérifiez le démarrage de l’exécuteur et l’accès au réseau. Pour les environnements auto-hébergés, vérifiez la configuration de la connexion.
sandbox_error Cause : L’initialisation du bac à sable ou l’exécution dans celui-ci a échoué.
Solution : Examinez les commandes d’initialisation, les paquets, les fichiers d’entrée et l’erreur de l’environnement.
executor_version_incompatible Cause : La version de l’exécuteur de la session n’est pas prise en charge.
Solution : Mettez l’exécuteur à niveau avant de créer une nouvelle session.
idle_timeout Cause : L’environnement hébergé a expiré après une période d’inactivité.
Solution : Créez une nouvelle session et fournissez à nouveau les données d’entrée.
internal_error Cause : Une défaillance interne a empêché la session ou l’environnement de s’initialiser.
Solution : Patientez avant de relancer l’initialisation. Si l’échec persiste, contactez l’assistance.

Reprise

Réessayer après une erreur temporaire

Suivez cette procédure en cas de dépassement d’une limite de débit, de surcharge, de dépassement du délai d’attente ou de défaillance temporaire du service. En cas de données d’entrée invalides, de problème d’identifiants ou de limite de facturation atteinte, corrigez le problème avant de réessayer.

  1. Vérifiez le résultat de l’opération. Si une session a été créée, récupérez-la ainsi que le tour et les éléments enregistrés. Si le tour est toujours en cours, continuez à le suivre. S’il s’est terminé avec succès, utilisez son résultat.
  2. Vérifiez les actions déjà effectuées. Même si le tour a échoué, l’agent peut déjà avoir modifié des fichiers ou appelé des outils externes. Vérifiez les effets de ces actions avant de demander à l’agent de les répéter.
  3. Patientez et limitez le nombre de tentatives. Suivez les consignes générales pour réessayer. Respectez le délai indiqué par Retry-After dans les réponses HTTP et fixez un nombre maximal de tentatives ou une échéance.
  4. Relancez la requête ou démarrez un nouveau tour. En cas d’erreur HTTP, vérifiez le résultat de l’opération initiale avant de la relancer. Si un tour a échoué, attendez que la session passe à l’état idle, puis envoyez un message de suivi pour demander à l’agent de reprendre uniquement le travail inachevé. Un nouveau tour démarre dans la conversation existante.

Examinez les résultats des outils même si le tour se termine avec succès. Arrêtez les tentatives automatiques si l’erreur change ou si le nombre maximal de tentatives est atteint.

Corriger les données d’entrée invalides

Corrigez le champ indiqué par error.param ou error.message avant de renvoyer la requête.

En cas d’erreur de taille, réduisez la taille des données d’entrée et du schéma de sortie ou du résultat de l’outil avant de réessayer. Si la configuration de l’agent est trop volumineuse, créez une nouvelle session avec des instructions et des définitions d’outils plus courtes.

Pour connaître les exigences de téléversement et consulter des exemples, voir Résoudre les erreurs de téléversement. Si le message signale un problème d’image, vérifiez les données de l’image ou son URL.

Interruption du flux

Un événement error ou une interruption du flux ne permet pas de déterminer l’état final du tour. Suivez la procédure pour rétablir un flux interrompu afin de vous reconnecter et de vérifier le travail enregistré avant de renvoyer les données d’entrée. Si la session récupérée indique status: "failed" ou si vous recevez agent.session.failed, cessez les tentatives de reconnexion et suivez les consignes de reprise après un échec de session.

En cas d’erreur persistante, indiquez les identifiants de la requête, de la session et du tour dans votre demande d’assistance.