Erreurs d'API

Cette page fournit une 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 les erreurs pour différents types de requêtes.

Codes d'erreur de l'API standard

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 de manière programmatique.

Code État HTTP Description Action recommandée
invalid_request 400 Requête erronée La charge utile de la requête est mal formulée ou contient des paramètres non valides. Vérifiez la syntaxe et les paramètres de votre requête par rapport à la documentation de référence de l'API.
failed_precondition 400 Requête erronée La demande ne peut pas être traitée, car une condition requise n'est pas remplie (par exemple, la facturation est désactivée). Vérifiez l'état de facturation du projet ou les conditions requises pour le compte.
out_of_range 416 Requested Range Not Satisfiable : la plage spécifiée par le champ d'en-tête Range de la requête ne peut pas être satisfaite. Le paramètre de requête est en dehors de la plage valide. Vérifiez les valeurs et les limites des paramètres.
parameter_unknown 400 Requête erronée La requête contient un paramètre inconnu. Supprimez le paramètre non reconnu et réessayez.
authentication 401 Non autorisé La clé API est manquante, non valide ou a expiré. Vérifiez votre clé API.
payment_required 402 Payment Required Votre solde de crédits prépayés est épuisé. Ajoutez des crédits à votre compte de facturation ou activez la recharge automatique. Ne pas réessayer : la requête n'aboutira pas tant que des crédits n'auront pas été ajoutés.
permission_denied 403 Interdit Votre clé API n'est pas autorisée à accéder à 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é est introuvable. Vérifiez le nom du modèle ou revenez à un autre modèle.
already_exists 409 Conflit L'entité que vous avez tenté de créer existe déjà. Vérifiez si la ressource existe déjà avant de la recréer.
aborted 409 Conflit L'opération a été annulée en raison d'un conflit ou d'un échec de vérification de la simultanéité. Réessayez d'envoyer la requête à un niveau d'application supérieur.
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 que le quota soit réinitialisé ou demandez une augmentation de quota.
too_many_requests 429 Trop de requêtes Vous avez effectué trop de demandes en peu de temps. Attendez et réessayez avec un intervalle exponentiel entre les tentatives.
cancelled 499 Client Closed Request Le client a annulé la demande avant qu'elle ne soit traité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.
unimplemented 501 Not Implemented (501 Non implémenté) L'opération ou la fonctionnalité n'est pas implémentée ni prise en charge. Vérifiez les fonctionnalités de l'API ou passez à une fonctionnalité compatible.
service_unavailable 503 Service indisponible. Le service est temporairement surchargé ou indisponible. Attendez et réessayez avec un intervalle exponentiel entre les tentatives.
deadline_exceeded 504 Expiration du délai de la passerelle La demande n'a pas été traitée dans le délai imparti. Supprimez ou augmentez le paramètre de délai du client pour utiliser la valeur par défaut du serveur.

Codes de génération bloquée

Ces codes d'erreur indiquent que des restrictions concernant les règles, la sécurité ou le contenu ont bloqué la sortie du modèle. Lorsque vous recevez l'un de ces codes, modifiez votre saisie et réessayez.

Code Description
safety La requête a été bloquée en raison de non-respect des règles de sécurité (contenu nuisible).
recitation La demande a été bloquée en raison de restrictions liées aux droits d'auteur ou à la récitation.
language Une langue non acceptée a bloqué la demande.
prohibited_content Les consignes relatives au contenu interdit ont bloqué la demande.
spii La demande a été bloquée en raison de restrictions liées aux informations sensibles permettant d'identifier personnellement l'utilisateur.
blocklist La requête a été bloquée, car elle contenait des termes interdits figurant sur une liste de blocage.
image_safety La génération d'image a été bloquée en raison d'un non-respect des règles de sécurité.
image_prohibited_content Les consignes relatives au contenu interdit ont bloqué la génération d'images.
image_recitation La génération d'images a été bloquée en raison de restrictions liées aux droits d'auteur ou à la récitation.
image_other La génération d'images a été bloquée pour des raisons non spécifiées.
content_blocked Une raison non spécifiée liée aux règles a bloqué la demande.

Codes d'erreur de génération

Ces codes d'erreur indiquent un problème structurel avec la sortie générée du 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 généré un appel de fonction qui n'a pas pu être analysé.
malformed_tool_call Le modèle a généré un appel d'outil qui n'a pas pu être analysé.
unexpected_tool_call Le modèle a appelé un outil qui n'était pas 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 Il manque une signature de pensée obligatoire dans la réponse.

Format de la réponse d'erreur

Toutes les erreurs de l'API Interactions renvoient un objet error contenant un code et un message. Par exemple, si vous transmettez un type d'outil non compatible, le résultat suivant s'affiche :

{
  "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 de ce qui s'est mal passé.

Comment les erreurs sont-elles communiquées ?

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

Requêtes HTTP standards

Pour les requêtes standards (non en flux continu), 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 de streaming (SSE)

Pour les requêtes de streaming (stream: true), l'API envoie des événements d'erreur sur 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