Erreurs d'API

Cette page fournit une documentation de référence pour tous les codes d'erreur de l'API Interactions, décrit le format de la réponse d'erreur et explique comment l'API fournit des erreurs pour différents types de requêtes.

Codes d'erreur standards de l'API

Ces codes d'erreur généraux au niveau de la requête correspondent aux codes d'état HTTP standards. Utilisez le champ code dans la logique de votre application pour gérer les erreurs par programmation.

Code État HTTP Description Action recommandée
invalid_request 400 Requête incorrecte La requête est mal formée ou contient des paramètres non valides. Vérifiez vos entrées par rapport à la documentation de référence de l'API.
parameter_unknown 400 Requête incorrecte La requête contient un paramètre inconnu. Supprimez le paramètre non reconnu et réessayez.
authentication 401 Unauthorized La clé API est manquante ou non valide. Vérifiez votre clé API.
permission_denied 403 Interdit Votre clé API n'est pas autorisée pour cette ressource. Vérifiez les autorisations de votre clé API et l'accès au projet.
not_found 404 Not Found Impossible de trouver la ressource demandée. Vérifiez le chemin d'accès et les paramètres de la ressource.
model_not_found 404 Not Found Le modèle spécifié n'a pas été trouvé. Vérifiez le nom du modèle ou utilisez un autre modèle.
rate_limit_exceeded 429 Trop de requêtes Vous avez dépassé la limite de requêtes ou de jetons par minute ou par seconde. Attendez et réessayez avec un intervalle exponentiel entre les tentatives.
quota_exceeded 429 Trop de requêtes Vous avez dépassé votre quota quotidien. Attendez la réinitialisation du quota ou demandez une augmentation de quota.
cancelled 499 Client Closed Request Le client a annulé la requête avant qu'elle ne soit terminée. Aucune action de votre part n'est requise. Cela signifie généralement que le client s'est déconnecté.
api_error 500 Erreur interne au serveur. Une erreur inattendue s'est produite sur le serveur. Réessayez d'envoyer la requête. Si le problème persiste, contactez l'assistance.
service_unavailable 503 Service indisponible. Le service est temporairement surchargé ou en panne. Attendez et réessayez avec un intervalle exponentiel entre les tentatives.

Codes de génération bloquée

Ces codes d'erreur indiquent que des restrictions liées aux règles, à la sécurité ou au contenu ont bloqué la sortie du modèle. Lorsque vous recevez l'un de ces codes, modifiez votre entrée et réessayez.

Code Description
safety Des violations de sécurité (contenu nuisible) ont bloqué la requête.
recitation Des restrictions liées aux droits d'auteur ou à la récitation ont bloqué la requête.
language Une langue non acceptée a bloqué la requête.
prohibited_content Les consignes relatives au contenu interdit ont bloqué la requête.
spii Les restrictions liées aux informations personnelles sensibles ont bloqué la requête.
blocklist Des termes interdits figurant sur une liste de blocage ont bloqué la requête.
image_safety Des violations de sécurité ont bloqué la génération d'images.
image_prohibited_content Les consignes relatives au contenu interdit ont bloqué la génération d'images.
image_recitation Des restrictions liées aux droits d'auteur ou à la récitation ont bloqué la génération d'images.
image_other Des raisons non spécifiées ont bloqué la génération d'images.
content_blocked Une raison non spécifiée liée aux règles a bloqué la requête.

Codes d'erreur de génération

Ces codes d'erreur indiquent un problème structurel avec la sortie générée par le modèle (par exemple, un appel de fonction mal formé ou un appel d'outil non déclaré).

Code Description
malformed_function_call Le modèle a produit un appel de fonction qui n'a pas pu être analysé.
malformed_tool_call Le modèle a produit un appel d'outil qui n'a pas pu être analysé.
unexpected_tool_call Le modèle a appelé un outil qui n'a pas été déclaré dans la requête.
no_image Le modèle n'a pas pu générer d'image.
too_many_tool_calls Le modèle a généré plus d'appels d'outils que ce qui est autorisé.
missing_thought_signature La réponse ne contient pas de signature de pensée requise.

Format de la réponse d'erreur

Toutes les erreurs de l'API Interactions renvoient un error objet contenant un code et message. Par exemple, la transmission d'un type d'outil non accepté renvoie :

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Champ Type Description
code chaîne Code d'erreur lisible par une machine au format snake_case.
message chaîne Description lisible par l'humain du problème.

Comment les erreurs sont-elles fournies ?

L'API fournit les erreurs différemment selon que vous effectuez une requête HTTP standard ou une requête en streaming (SSE).

Requêtes HTTP standards

Pour les requêtes standards (non en streaming), l'API définit le code d'état de la réponse HTTP (par exemple, 400 Bad Request, 401 Unauthorized, ou 429 Too Many Requests) et renvoie un objet error dans le corps de la réponse JSON :

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Requêtes en streaming (SSE)

Pour les requêtes en streaming (stream: true), l'API envoie des événements d'erreur via le flux d'événements envoyés par le serveur (SSE) avec event_type défini sur "error". Le champ error contient la même structure code et message :

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Pour obtenir le schéma complet des événements SSE, consultez la documentation de référence de l'API Interactions.

Étape suivante