Documentation

Référence des erreurs API v2

Référencez tous les codes d’erreur déclarés de l’API v2, leur statut HTTP et leur déclencheur en production.

Les erreurs de l’API v2 utilisent un objet error structuré :

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Certaines erreurs de validation incluent aussi un champ details optionnel, avec des informations au niveau du champ :

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

Chaque réponse v2 inclut un en-tête x-request-id. Indiquez cette valeur lorsque vous contactez le support. Développez votre logique en vous basant sur error.code ; les messages et les détails de validation fournissent un contexte lisible par un humain.

Catalogue des erreurs

Le tableau inclut les 30 codes déclarés par l’API v2. Un tiret signifie que le code est réservé et n’a aucun point d’appel en production dans la v2, si bien qu’aucun statut HTTP ni déclencheur n’est actuellement défini.

CodeStatut HTTPQuand cela se produitRemarques
VALIDATION_INVALID_BODY400Un corps de requête, une valeur de chemin, une valeur de requête, une limite, un curseur, une source de conversation, un type de source, ou une entrée de traitement de source échoue à la validation.details n’est inclus que lorsque le point d’appel le fournit.
VALIDATION_INVALID_JSON400Le point de terminaison de chat, de relance, de résultat d’outil, ou d’évaluation reçoit un corps qui n’est pas un JSON valide.Les autres points de terminaison de gestion interprètent un JSON malformé comme un corps invalide.
AUTH_MISSING_API_KEY401Un point de terminaison authentifié ne reçoit aucun en-tête Authorization, ou la valeur ne commence pas par Bearer .Le point de terminaison de santé ne nécessite pas d’authentification.
AUTH_INVALID_API_KEY401La clé API Bearer ne peut pas être validée.Utilisez une clé API active de l’espace de travail.
AUTH_EXPIRED_API_KEY—Réservé ; non émis actuellement par une route v2 en production.Aucun statut ni déclencheur n’est défini.
SUBSCRIPTION_PLAN_REQUIRED403La clé API est valide, mais l’espace de travail associé ne dispose pas de la fonctionnalité de forfait apiAccess.L’accès à l’API nécessite un forfait Hobby ou supérieur, avec une facturation active.
SUBSCRIPTION_API_RESTRICTED_PLAN403Un appelant active le réentraînement automatique sans accès au forfait requis, ou soumet une URL vidéo sans accès à la transcription vidéo.La clé API elle-même reste valide.
AUTH_INSUFFICIENT_PERMISSIONS—Réservé ; non émis actuellement par une route v2 en production.Aucun statut ni déclencheur n’est défini.
AGENT_NOT_FOUND404Une requête propre à un agent désigne un agent qui n’existe pas ou n’appartient pas au compte de la clé API.Les échecs de propriété utilisent la même réponse que les agents introuvables.
RESOURCE_NOT_FOUND404Une conversation API v2 requise par une opération de détail, de message, de relance, ou d’évaluation est introuvable.Les opérations de mutation et de liste de messages ne concernent que les conversations API v2.
RESOURCE_DOCUMENT_NOT_FOUND404Une suppression de source désigne un document qui n’existe pas pour l’agent.Les ID de document invalides, non conformes au format UUID, renvoient plutôt VALIDATION_INVALID_BODY.
RESOURCE_MESSAGE_NOT_FOUND404L’évaluation désigne un ID de message invalide ou un message qui ne se trouve pas dans la conversation API v2 spécifiée.Les ID de message sont des valeurs numériques positives, sérialisées sous forme de chaînes dans les réponses.
RESOURCE_MESSAGE_NOT_ASSISTANT422L’évaluation cible un message qui n’est pas un message de l’assistant IA.Les messages utilisateur et les enregistrements d’outil ne peuvent pas recevoir d’évaluation.
RESOURCE_TOOL_CALL_NOT_FOUND404Le point de terminaison de résultat d’outil ne parvient pas à faire correspondre le toolCallId fourni à une action client en attente.L’appel est inconnu, expiré ou appartient à une autre conversation API v2.
QUOTA_CHATBOT_LIMIT403La création d’un agent dépasserait la limite de chatbots de l’espace de travail.Supprimez un agent ou passez à un forfait supérieur avant de réessayer.
QUOTA_STORAGE_LIMIT403Le traitement d’une source texte ou Q&R signale une limite de stockage, une nouvelle URL ne peut pas tenir dans le stockage disponible, ou la création d’une tâche d’URL signale un échec de quota.Le réentraînement d’une URL existante ne consomme pas de stockage de document supplémentaire.
CHAT_MODEL_NOT_ALLOWED403Une mise à jour des paramètres d’IA sélectionne un modèle indisponible sur le forfait de l’espace de travail.Choisissez un modèle autorisé ou passez à un forfait supérieur.
CHAT_CREDITS_EXHAUSTED—Réservé ; non émis actuellement par une route v2 en production.Aucun statut ni déclencheur n’est défini.
CHAT_AGENT_CREDITS_EXHAUSTED—Réservé ; non émis actuellement par une route v2 en production.Aucun statut ni déclencheur n’est défini.
CHAT_CONVERSATION_MISMATCH404Une requête de chat fournit un conversationId bien formé (≤128 caractères) qui ne correspond à aucune conversation API v2 pour l’agent.Un conversationId de plus de 128 caractères est rejeté plus tôt avec 400 VALIDATION_INVALID_BODY, et non avec ce code. Omettre conversationId démarre une nouvelle conversation.
CHAT_RETRY_MESSAGE_NOT_FOUND404La relance reçoit un ID de message non positif ou non entier, ou la cible n’est pas un message de l’assistant IA dans la conversation API v2.Les enregistrements d’outil ne sont pas des cibles de relance.
CHAT_RETRY_NO_USER_MESSAGE400La cible de la relance n’a pas de message utilisateur antérieur à rejouer.La relance régénère à partir du tour utilisateur immédiatement avant la réponse de l’assistant sélectionnée.
INSTAGRAM_NOT_CONNECTED404Une requête de canal Instagram désigne un agent sans connexion Instagram.GET /channels/instagram répond par { "connected": false } plutôt que par ce code.
INSTAGRAM_RECONNECT_REQUIRED409Le passage des commentaires aux messages privés est activé sans l’autorisation d’accéder aux commentaires, ou des amorces de conversation sont publiées sur une connexion qui n’est pas connected.Reconnectez le compte sous Publier → Instagram dans le tableau de bord.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Une automatisation comment_to_dm ou story_leads est activée alors qu’une autre instance active cible déjà la même publication ou story.Désactivez l’autre instance ou ciblez une autre publication ou story. Les brouillons ne sont jamais rejetés.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Une automatisation générique comment_to_dm ou story_leads (postScope / storyScope "any") est activée alors qu’une automatisation générique active de ce type existe déjà.Désactivez d’abord l’automatisation générique existante ou ciblez une publication ou une story précise.
INSTAGRAM_SYNC_IN_PROGRESS409Un PATCH du menu persistant ou des amorces de conversation chevauche une synchronisation de la même ressource pour le même agent.Réessayez une fois la publication ou la suppression en cours terminée.
INSTAGRAM_SYNC_FAILED502La synchronisation du menu persistant ou des amorces de conversation a échoué.details.code est un code d’échec autorisé ; details.http_status et details.meta_code sont numériques ou valent null. Le texte du message de Meta n’est jamais renvoyé, et l’instantané actif stocké décrit toujours le dernier état confirmé.
RATE_LIMIT_TOO_MANY_REQUESTS—Réservé ; non émis actuellement par une route v2 en production.Aucun délai de nouvelle tentative ni comportement Retry-After n’est défini.
INTERNAL_SERVER_ERROR500La création d’une tâche d’URL échoue pour une raison autre qu’un quota, ou une relance non-streaming ne produit aucun message d’assistant persisté.Indiquez x-request-id lorsque vous signalez l’échec.

Référence associée