Erreurs d'exécution des outils
Chaque code TOOL_VENDOR_ qu'un outil d'extension gouverné peut renvoyer, ce qui l'a provoqué et si une nouvelle tentative est utile.
Lorsqu'un outil d'extension échoue, Scrydon renvoie un code stable TOOL_VENDOR_*
plutôt que l'erreur sous-jacente. Cette page liste chaque code, ce qui le provoque
et ce qu'il faut faire.
À quoi ressemble un échec
Un appel d'outil en échec renvoie :
{
"success": false,
"output": {},
"error": "TOOL_VENDOR_EGRESS_DENIED",
"message": "The destination is not on the approved egress list for this connection.",
"metadata": { "retryable": false }
}Dans l'exécution d'un workflow, le même code apparaît en regard du nœud qui a échoué :
{ "failedNodes": 1, "errors": ["b40d978e-…: TOOL_VENDOR_EGRESS_DENIED"] }Branchez votre logique sur error. message est une phrase lisible associée à ce code, destinée
à la personne qui lit l'échec — elle est stable pour un code donné mais peut être reformulée, ce n'est donc
pas une clé de branchement. Elle est sélectionnée par le code et n'interpole jamais la
raison sous-jacente ; elle ne vous apprend donc rien que le code ne disait déjà.
Le détail est volontairement masqué. Les outils d'extension s'exécutent dans une microVM isolée sur vos données, avec des identifiants appartenant à votre organisation. Les erreurs brutes du fournisseur, les éléments d'identification, les détails réseau et les constats DLP ne remontent jamais jusqu'à l'appelant, car l'appelant est souvent un modèle. Vous obtenez un code stable ; la raison complète reste côté serveur.
La politique a bloqué l'appel
La gouvernance a refusé la requête. Ce sont des décisions, pas des pannes — réessayer une requête identique échoue toujours de la même manière.
| Code | Cause | Que faire |
|---|---|---|
TOOL_VENDOR_NOT_SUPPORTED | L'archive n'a aucune implémentation pour le hook demandé par la plateforme (par exemple un récupérateur de découverte de modèles que le fournisseur n'a jamais déclaré) | Rien à réessayer : la plateforme le traite comme une réponse vide. Si un outil censé exister le renvoie, c'est que l'archive ne l'exporte pas |
TOOL_VENDOR_EGRESS_DENIED | La destination ne figure pas dans la liste d'egress approuvée pour cette connexion | Ajoutez l'hôte aux destinations autorisées de la connexion |
TOOL_VENDOR_DESTINATION_DENIED | L'URL construite par l'outil est mal formée, ou son hôte n'est pas autorisé | Vérifiez les entrées de l'outil, puis les hôtes autorisés de la connexion |
TOOL_VENDOR_REDIRECT_DENIED | La destination a redirigé vers un emplacement que la politique n'autorise pas | Autorisez la cible de la redirection, ou pointez l'outil vers l'URL finale |
TOOL_VENDOR_DLP_BLOCKED | La DLP sortante a détecté une correspondance dans la requête réellement émise par l'outil | Supprimez ou reclassifiez les données bloquées, ou modifiez la politique DLP |
TOOL_VENDOR_RESPONSE_SECRET_BLOCKED | La réponse du fournisseur contenait des données ressemblant à des identifiants et a été retenue | Attendu lorsqu'un fournisseur renvoie des secrets en écho ; à investiguer si inattendu |
TOOL_VENDOR_HEADER_DENIED | L'outil a défini un en-tête interdit ou un en-tête proxy-* | Corrigez l'outil ; ces en-têtes appartiennent au broker d'egress |
TOOL_VENDOR_CREDENTIAL_PLACEMENT_DENIED | Un identifiant a été placé à un endroit que son mode d'authentification interdit — par exemple un secret d'en-tête dans un corps | Corrigez le placement selon le mode d'authentification de l'outil |
TOOL_VENDOR_UNKNOWN_CREDENTIAL_PLACEHOLDER | La requête contenait encore un placeholder scrydon_secret_* auquel rien n'était lié | Liez chaque placeholder référencé par l'outil, ou supprimez-le |
TOOL_VENDOR_CLI_NOT_CONFIGURED | L'id de CLI demandé n'est pas déclaré par le manifeste de cette extension | Vérifiez l'id de CLI par rapport aux clis déclarés de l'extension |
TOOL_VENDOR_CLI_IDENTITY_NOT_CONFIGURED | Cette CLI nécessite une identité d'application (service principal) que ce déploiement n'a pas configurée | Configurez les identifiants de service principal de l'organisation pour cette extension avant d'utiliser une CLI credentialHosts/bootstrap |
TOOL_VENDOR_CLI_NO_BINDABLE_CREDENTIAL | L'identifiant de la CLI n'a pu être lié à aucun de ses hôtes d'egress accordés — y compris une CLI avec endpointEnv dont l'organisation a configuré plus d'un point de terminaison | Accordez à la CLI au moins un hôte sans joker auquel son identifiant peut être lié ; pour endpointEnv, configurez exactement un point de terminaison |
TOOL_VENDOR_CLI_ISOLATION_REQUIRED | Un dispatch de CLI a atteint l'exécution sans niveau microVM | Interne ; signalez-le si vous le voyez — le dispatch de CLI est censé toujours être admis en microVM |
TOOL_VENDOR_CLI_INVALID_INPUT | L'entrée du dispatch de CLI ne correspondait pas à la forme argv { args, stdin? } attendue par le runner | Vérifiez les arguments de l'appel d'outil par rapport à la forme d'invocation déclarée de la CLI |
TOOL_VENDOR_CLI_QUERY_PARAM_CREDENTIAL | L'identifiant de cette CLI est configuré pour une transmission par paramètre de requête, que l'estampillage ne peut pas assurer | Reconfigurez l'identifiant pour une transmission par en-tête, ou contactez le support |
TOOL_VENDOR_CLI_INVALID_CREDENTIAL_HOSTS | Les credentialHosts déclarés de la CLI nomment un hôte hors de l'ensemble d'egress accordé, un hôte réservé à l'émulation de jeton, un joker, ou le même hôte deux fois | Corrigez la déclaration credentialHosts du manifeste de l'extension |
TOOL_VENDOR_CLI_CREDENTIAL_HOSTS_REQUIRED | La CLI ne déclare aucun credentialHosts, et la liste d'egress propre à l'extension comporte plus d'un hôte (un point de terminaison configuré par l'organisation n'est pas compté) ; l'hôte auquel appartient l'identifiant n'est donc pas deviné | Ajoutez une entrée credentialHosts limitée aux hôtes, nommant les hôtes pour lesquels l'identifiant de la connexion est valide |
TOOL_VENDOR_CLI_DISALLOWED_PREAMBLE_PLACEHOLDER | Le bootstrap.preamble de la CLI utilisait un placeholder hors de l'ensemble autorisé, ou un placeholder mal formé | Corrigez le modèle bootstrap.preamble du manifeste de l'extension |
EXEC_ACTION_CONFIRMATION_DECLINED | Une personne a refusé la requête CLI destructive pour laquelle cet appel nécessitait une approbation. Rien n'a été réexécuté ni envoyé, et l'agent poursuit son étape | Rien à réessayer : répéter l'appel sollicite à nouveau la personne. Voir Approuver une suppression |
CLI_CONFIRMATION_AFTER_WRITE | Une commande CLI a effectué une requête destructive après qu'une requête antérieure de la même commande avait déjà été envoyée en écriture. Personne n'a été sollicité, car approuver réexécuterait la commande et renverrait cette écriture ; la requête destructive n'a pas été envoyée | Exécutez la commande destructive seule, dans un appel distinct. Vérifiez le résultat de l'écriture précédente avant de la répéter : son issue est inconnue. Voir Approuver une suppression |
Un appel CLI sur une extension non revue n'atteint jamais ce tableau. Seules
les versions Scrydon first-party et revues peuvent déclarer une CLI (v1.0.0). En dispatcher
une sur une extension installée par l'organisation est refusé avant le début de l'exécution, avec
CAPABILITY_NOT_CONFIGURED — le code général de la plateforme signifiant « cette capacité n'est pas
disponible », et non un résultat TOOL_VENDOR_*.
Limites et délais
| Code | Cause | Réessayer ? |
|---|---|---|
TOOL_VENDOR_TIMEOUT | L'invocation a dépassé son délai | Oui, si l'opération peut être répétée sans risque |
TOOL_VENDOR_EGRESS_TIMEOUT | Une requête sortante unique a dépassé son délai | Oui, même réserve |
TOOL_VENDOR_EGRESS_BUDGET_EXHAUSTED | L'outil a effectué plus de requêtes sortantes que son budget ne le permet | Non — réduisez le nombre de requêtes de l'outil |
TOOL_VENDOR_REQUEST_TOO_LARGE | La requête sortante a dépassé la taille maximale | Non — envoyez moins |
TOOL_VENDOR_RESULT_TOO_LARGE | Le résultat de l'outil a dépassé la taille maximale | Non — renvoyez moins, ou paginez |
TOOL_VENDOR_CANCELLED | L'exécution parente a été annulée | Non — lancez une nouvelle exécution |
TOOL_VENDOR_EGRESS_CANCELLED | Une requête sortante a été annulée en cours de route | Non |
Un dépassement de délai ne vous indique pas si la requête a atteint la destination. Pour tout ce qui a des effets de bord, réconciliez avant de réessayer plutôt que de supposer qu'elle n'a pas été validée.
L'outil ou son archive a échoué
| Code | Cause | Que faire |
|---|---|---|
TOOL_VENDOR_EXECUTION_FAILED | L'outil a levé une exception, ou un échec sans code plus spécifique | Voir Obtenir la vraie raison — c'est le code fourre-tout |
TOOL_VENDOR_PROTOCOL_INVALID | Le cadrage de la requête, du résultat ou des journaux de l'archive était mal formé ou hors limites | Corrigez ou mettez à jour la version du code |
TOOL_VENDOR_ARTIFACT_HASH_MISMATCH | Les octets de l'archive ne correspondaient pas à l'empreinte épinglée pour cette exécution | Réinstallez l'extension ; si cela se reproduit, traitez-le comme une falsification |
TOOL_VENDOR_INVOCATION_BINDING_MISMATCH | L'invocation ne correspondait pas à l'artefact auquel elle était liée | Réinstallez l'extension et réessayez |
TOOL_VENDOR_ALREADY_INVOKED | Un bac à sable à usage unique a reçu une seconde invocation | Aucune action — le bac à sable est à usage unique par conception |
TOOL_VENDOR_UNAUTHORIZED | Le bac à sable a rejeté une invocation non authentifiée | Interne ; signalez-le si vous le voyez |
TOOL_VENDOR_REQUEST_INVALID | La requête sortante construite par l'outil est mal formée — un encodage de corps invalide, ou un corps sur un GET/HEAD | Corrigez la construction de la requête de l'outil |
TOOL_VENDOR_EGRESS_PROTOCOL_INVALID | Le bac à sable et le broker d'egress étaient en désaccord sur le cadrage | Interne ; signalez-le si vous le voyez |
TOOL_VENDOR_CONTEXT_INVALID | Les identifiants n'ont pas pu être projetés dans le bac à sable pour cet appel | Revérifiez les identifiants et les liaisons de la connexion |
TOOL_VENDOR_EXECUTION_FAILED est aussi le code auquel se ramène tout code non reconnu ;
c'est donc le code que vous verrez le plus probablement et le moins spécifique. Il ne
signifie pas à lui seul que la logique propre de l'outil a échoué.
La plateforme n'a pas pu l'exécuter
Il s'agit de conditions d'infrastructure. Sur Scrydon Cloud, c'est à nous de les corriger ; si vous êtes auto-hébergé, elles désignent votre déploiement.
| Code | Cause |
|---|---|
TOOL_VENDOR_ISOLATION_UNAVAILABLE | Le bac à sable n'a pas pu être provisionné — aucune capacité d'isolation, ou le pod n'a pas pu être planifié |
TOOL_VENDOR_ATTESTATION_REQUIRED | La frontière d'exécution du fournisseur n'a pas de preuve actuelle ; l'exécution refuse donc plutôt que de se dégrader |
TOOL_VENDOR_EGRESS_UNAVAILABLE | Le broker d'egress n'a pas pu être rattaché au bac à sable |
TOOL_VENDOR_BROKER_NOT_READY | L'outil a émis un appel sortant avant que son autorisation d'egress ne soit installée |
TOOL_VENDOR_EGRESS_FAILED | Le transport sortant a échoué avant une réponse |
TOOL_VENDOR_MANAGED_EXECUTION_UNAVAILABLE | Le niveau d'exécution en processus géré était injoignable |
TOOL_VENDOR_GRANT_UNAVAILABLE | Le bac à sable n'a pas pu récupérer son autorisation à usage unique |
TOOL_VENDOR_GRANT_INVALID | L'autorisation récupérée n'a pas été validée |
TOOL_VENDOR_GRANT_TIMEOUT | La récupération de l'autorisation a dépassé son délai — lors de la connexion, de l'attente d'une autorisation prête ou de la lecture du corps de l'autorisation |
TOOL_VENDOR_GRANT_EXPIRED | Le délai propre de l'autorisation a expiré avant que le bac à sable ne l'utilise |
TOOL_VENDOR_GRANT_INSTALL_FAILED | L'installation de l'autorisation a échoué pour une raison autre que les quatre ci-dessus |
TOOL_VENDOR_GRANT_STORE_UNAVAILABLE | Le magasin d'autorisations était injoignable |
TOOL_VENDOR_DLP_POLICY_UNAVAILABLE | La politique DLP n'a pas pu être chargée ; l'appel a donc échoué en mode fermé |
TOOL_VENDOR_EGRESS_POLICY_UNAVAILABLE | La politique d'egress n'a pas pu être chargée ; l'appel a donc échoué en mode fermé |
TOOL_VENDOR_CLEANUP_FAILED | Il n'a pas pu être prouvé que le bac à sable ou ses autorisations avaient été détruits |
TOOL_VENDOR_PLATFORM_SDK_UNAVAILABLE | L'outil déclare platformOperations, et son exécution en microVM n'a pas pu recevoir le rappel du SDK de la plateforme ; rien n'a été exécuté |
Les deux codes *_POLICY_UNAVAILABLE sont délibérés : lorsque la politique de gouvernance
ne peut pas être chargée, l'appel est refusé plutôt qu'exécuté sans gouvernance.
Si l'appel a été envoyé
Lorsqu'un agent appelle un outil depuis son bac à sable, ces codes indiquent à l'agent si l'appel a atteint l'outil. Chacun est enregistré sous l'id de l'appel. Présenter à nouveau le même id d'appel renvoie la même réponse et n'envoie jamais l'appel.
| Code | Cause | Que faire |
|---|---|---|
EXEC_ACTION_NOT_DISPATCHED | La plateforme a refusé l'appel avant de l'envoyer. Elle n'a pas pu lire la classification de ce que ce tour d'agent a déjà lu, et elle n'envoie jamais un appel qu'elle ne peut pas classifier. Rien n'a été envoyé : l'appel n'a donc eu aucun effet. retryable vaut true uniquement lorsque la cause était temporaire : le magasin d'état de la plateforme a expiré, était injoignable ou a répondu par une erreur serveur. Une cause durable donne retryable: false : le magasin d'état n'est pas configuré, ou l'enregistrement stocké est illisible | Lorsque retryable vaut true, réessayez sous la forme d'un nouvel appel. Le nouvel appel est vérifié depuis le début : un appel qui requiert une approbation sollicite donc à nouveau une personne, car une approbation donnée pour l'appel refusé n'est pas reportée. Lorsque retryable vaut false, ne réessayez pas, car la même cause le refuse à nouveau. Sur Scrydon Cloud, cette cause est à nous de corriger. Si vous auto-hébergez, vérifiez le magasin d'état Dapr du service agentic |
EXEC_ACTION_EXECUTION_GRANT_REQUIRED | L'appel a été fait pour un utilisateur et il est soumis à une classification, mais le run ne détient aucune autorisation d'exécution sous laquelle agir. Un appel fait pour un utilisateur ne peut pas également affirmer une classification : la plateforme l'a donc refusé avant de l'envoyer. Rien n'a été envoyé : l'appel n'a donc eu aucun effet. Toujours retryable: false | Ne réessayez pas : le même appel est refusé de la même façon. Démarrez le run de sorte qu'il porte une autorisation d'exécution (c'est le cas d'un run démarré par un utilisateur connecté), ou exécutez l'outil sans classification |
POLICY_BLOCKED, FORBIDDEN, CAPABILITY_NOT_CONFIGURED | La plateforme a refusé l'appel avant d'exécuter l'outil : le point de terminaison de l'outil n'est pas noté pour la classification que ce tour a lue (le message commence par EGRESS_BLOCKED_BY_CLEARANCE), le run n'est pas autorisé à utiliser l'outil, le compte connecté ne peut pas atteindre la ressource que nomme l'appel, ou l'outil n'est pas configuré pour ce tenant. Pour trancher le cas de la ressource, la plateforme peut d'abord demander au fournisseur, par une vérification en lecture seule, si le compte peut atteindre cette ressource ; l'appel lui-même n'est jamais envoyé. L'outil ne s'est jamais exécuté : l'appel n'a donc eu aucun effet. retryable vaut true uniquement lorsque la cause était temporaire : aujourd'hui, il s'agit d'un CAPABILITY_NOT_CONFIGURED levé parce que la plateforme n'a pas pu déterminer sous quel compte l'appel s'exécute sur la connexion (le propre compte du principal agissant, ou le compte par défaut de la connexion). Tous les autres refus ici sont retryable: false. Un POLICY_BLOCKED levé pour toute autre raison (un blocage DLP ou de modération, une requête CLI refusée par son niveau) peut survenir après l'envoi de l'appel : il est donc signalé comme EXEC_ACTION_EFFECT_UNKNOWN ou avec son propre code CLI | Lorsque retryable vaut true, réessayez sous la forme d'un nouvel appel ; l'outil ne s'est pas exécuté la première fois. Lorsqu'il vaut false, ne réessayez pas le même appel : il est refusé de la même façon. Pour EGRESS_BLOCKED_BY_CLEARANCE, un administrateur note le point de terminaison sous Paramètres → Gouvernance → Identité → Points de terminaison → Notations des points de terminaison, ou le run affirme une classification inférieure. Pour les deux autres, vérifiez l'installation, l'habilitation et la connexion de l'outil |
EXEC_ACTION_EFFECT_UNKNOWN | L'appel a peut-être atteint l'outil, mais son résultat n'a jamais été enregistré. Par exemple, la connexion a échoué après le départ de la requête, ou le résultat n'a pas pu être classifié. L'effet de bord a peut-être eu lieu. Toujours retryable: false | Ne répétez pas l'appel à l'aveugle. Vérifiez d'abord avec l'opération de lecture de l'outil si l'effet a eu lieu, puis décidez. Présenter à nouveau le même id d'appel renvoie ce code et n'envoie rien |
Quand réessayer
Ne déduisez pas la possibilité de réessayer à partir du code. Lisez metadata.retryable — il est défini
à partir des caractéristiques de transport de l'échec, de sorte qu'un même code peut être réessayable
dans un cas et pas dans un autre.
En règle générale :
- Ne réessayez jamais un refus de politique. La décision est déterministe.
- Réessayez avec un délai croissant en cas de conditions de capacité et de transport, et uniquement lorsque l'opération peut être répétée sans risque.
- Ne réessayez jamais automatiquement un appel à effets de bord après un dépassement de délai sans réconcilier d'abord — un dépassement de délai ne prouve pas que la requête n'a pas été validée.
- Attendez au moins
retryAftersecondes lorsque l'échec en comporte un. C'est le délai d'attente demandé par le fournisseur lui-même, et une nouvelle tentative qui arrive plus tôt se heurte à la même limite.
Dans votre extension, signalez une réponse non OK du fournisseur avec
throwExtensionHttpError(response) depuis
@scrydon/sdk-authoring/extensions/extension-failure plutôt qu'avec une simple
Error. Elle transporte le statut HTTP et le code d'erreur du fournisseur et, lorsque le
fournisseur a envoyé un en-tête retry-after-ms ou retry-after, son délai d'attente sous forme de
retryAfter en secondes entières. La plateforme transmet cette valeur comme retryAfter de l'erreur
et comme en-tête Retry-After de la réponse — une simple Error perd ces
trois éléments, si bien que chaque appelant ne peut que deviner.
Ce que la plateforme a déjà fait avant de vous répondre
La plateforme s'applique cette dernière règle à elle-même ; l'échec que vous recevez n'est donc pas la première chose qui a mal tourné — mais pour un appel d'outil, c'est la seule.
Chaque opération de la plateforme déclare si elle peut être répétée sans risque. Pour une opération en lecture seule, un échec passager du fournisseur est réessayé en interne (de manière bornée, avec délai croissant, auprès du même fournisseur — une nouvelle tentative n'autorise jamais à changer de fournisseur), de sorte qu'un échec qui vous parvient a déjà survécu à ces tentatives.
L'exécution d'outils n'est pas en lecture seule. Un appel d'outil gouverné peut créer un ticket, publier un message ou créer un enregistrement ; la plateforme effectue donc exactement une tentative et vous transmet l'échec. Il en va de même pour la création, le renouvellement ou la suppression d'un abonnement webhook. Deux conséquences :
- Un
TOOL_VENDOR_TIMEOUTqui vous parvient signifie qu'une tentative a dépassé son délai — et non trois. L'effet de bord peut tout de même avoir été validé. - Si vous réessayez, votre tentative est la deuxième, pas la cinquième. Prévoyez en conséquence, et réconciliez d'abord.
Fournir une idempotencyKey ne change rien à cela. La plateforme la transmet à
l'extension comme un champ d'entrée ordinaire ; que le fournisseur déduplique ou non sur cette clé
relève du comportement du fournisseur, pas d'une garantie de la plateforme ; la plateforme ne
réessaie donc pas sur la foi de celle-ci.
Obtenir la vraie raison
Si vous êtes auto-hébergé, la raison non tronquée se trouve côté serveur. API Platform la journalise
sous Governed vendor tool execution failed :
{
"code": "TOOL_VENDOR_EXECUTION_FAILED",
"executionId": "platform-parent-…",
"childExecId": "exec-…",
"executionTier": "microvm",
"planeReason": "…"
}planeReason est le texte de l'échec, limité à 512 caractères. Notez que
"The operation timed out." à cet endroit signifie qu'un budget côté client a expiré, et non que
la plateforme a décidé quoi que ce soit — généralement, le bac à sable n'a pas pu être provisionné à
temps.
Sur Scrydon Cloud, communiquez l'executionId au support.