Catégories d'erreurs

Si un appel de la passerelle échoue, l’erreur est renvoyée dans une enveloppe JSON uniforme :

{
  "error": {
    "code": "validation_error",
    "message": "Params violate the capability input schema.",
    "hint": "Call describe(id) and resend params matching input_schema.",
    "retryable": false,
    "audit_id": "audit_123"
  }
}

Codes d’erreur

Code	Signification pour les agents
validation_error	L’entrée ne correspond pas au schéma ; consulter describe et la corriger
auth_required	Clé Bearer absente ou invalide
scope_missing	La clé ne possède pas le scope requis
not_found / version_not_found	Vérifier l’identifiant ou la version
not_implemented	Visible dans le catalogue, mais non exécutable
dry_run_required	Effectuer d’abord un dry_run réussi avec les mêmes paramètres
precondition_failed	Prérequis métier manquant ; ne pas répéter aveuglément
conflict	Conflit avec l’état cible ; relire la situation et décider
rate_limited	Respecter retry_after_seconds
budget_exceeded	Clarifier le Wallet, le budget ou la politique
capability_disabled	Kill-Switch ou blocage de capacité actif
approval_required / approval_rejected	Passage de relais ou décision humaine nécessaire
upstream_error	Un service externe ou connecté n’a pas répondu correctement
internal_error	Réessayer plus tard ; si l’erreur se répète, transmettre l’identifiant d’audit au support

Règle de réaction

retryable: true autorise une nouvelle tentative avec un délai progressif, la même clé d’idempotence et la même intention. Avec retryable: false, corrigez d’abord la cause ou transmettez le cas à une personne.

HTTP 412 pendant l’inscription

La réponse HTTP 412 precondition_failed est attendue dans le parcours initial lorsqu’un prérequis métier manque encore.

Endpoint	Quand 412 est attendu	Réaction
GET /org/current	Avant la validation Owner ou, si agent_email est renseigné, avant la vérification e-mail de l’agent	Terminer l’étape OTP manquante, puis reprendre la consultation du statut
POST /keys/rotate	Avant la validation Owner ou la vérification e-mail requise de l’agent	Terminer le parcours initial ; ne pas remplacer une clé perdue par un nouveau bootstrap
POST /mcp/dry_run	Avant les OTP requis ou l’approbation de l’opérateur	Interroger /org/current jusqu’à ce que operator_approval_status vaille approved
POST /mcp/invoke	Avant les OTP requis ou l’approbation de l’opérateur	Ne pas effectuer de travail opérationnel ; appliquer la règle de consultation du statut ou de passage de relais

Attendez le code Owner, appelez POST /owner-otp/claim et, si agent_email est renseigné, effectuez aussi POST /agent-otp/verify. Consultez ensuite à nouveau le statut via /org/current. Si operator_approval_status reste longtemps à pending, suivez le Dépannage.

Pour continuer

Budgets et Kill-Switch