Démarrer

Codes d’erreur

acf-mcp utilise les codes d’erreur MCP/JSON-RPC standards. Chaque erreur embarque un champ kind (machine-readable), une description humaine et un hint d’action. Cette page liste les erreurs courantes et leur résolution.

→Astuce

Toutes les erreurs incluent un champ hint dans data. Quand votre agent reçoit une erreur, lisez le hint en priorité — il est calibré pour donner l’action de remédiation la plus courte.

Forme d’une erreur

Les erreurs suivent la spécification JSON-RPC 2.0 : un code numérique, un message court, un champ data structuré. Le champ data.kind est l’identifiant machine stable que vous devez matcher pour brancher votre logique de récupération.

error-example.jsonjson

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32602,
    "message": "InvalidEnumValue: autonomy_level must be one of N0, N1, N2, N3",
    "data": {
      "kind": "InvalidEnumValue",
      "field": "autonomy_level",
      "received": "N4",
      "allowed": ["N0", "N1", "N2", "N3"],
      "hint": "Use N3 for fully autonomous agents acting without human-in-the-loop."
    }
  }
}

Erreurs courantes

InvalidEnumValue-32602

Levée par les outils REASON quand un champ enum (autonomy_level, principle_id, role, etc.) ne correspond pas à la liste canonique de la doctrine. Le hint indique la valeur la plus probable au vu de l’entrée.

InputTooShort-32602

Levée quand un champ texte (typiquement description ou use_case_domain) fait moins de 20 caractères. Le moteur refuse les entrées trop pauvres pour produire une qualification opposable.

DoctrineSnapshotMismatch-32602

Levée quand l’appel demande un doctrine_version qui n’est pas la version actuellement chargée par le serveur. Mettez à jour le serveur (npx -y acf-mcp@latest) ou retirez le paramètre pour utiliser la version courante.

ResourceNotFound-32601

Levée par les outils READ quand l’URI acf://… demandée n’existe pas dans le corpus chargé. Vérifiez l’orthographe canonique via list-fiches ou search.

RateLimitExceeded-32000

Mode HTTP uniquement. L’IP appelante a dépassé 60 appels/minute (défaut). Réessayez après le retry-after indiqué dans data.

Erreurs de parsing et de protocole

ParseError-32700

Le client a envoyé du JSON invalide. Vérifiez votre sérialiseur.

InvalidRequest-32600

Le message JSON-RPC est mal formé (jsonrpc != 2.0, méthode manquante, etc.).

MethodNotFound-32601

Méthode inconnue. Utilisez tools/list et resources/list pour découvrir les méthodes supportées.

InternalError-32603

Erreur interne inattendue côté serveur. Ouvrez une issue en joignant les logs (cf. contributing).

Stratégies de récupération

InvalidEnumValue / InputTooShort — demandez à l’utilisateur de préciser, ou rappelez-vous des valeurs canoniques via la ressource glossary.
DoctrineSnapshotMismatch — informez l’utilisateur que la version de doctrine demandée n’est plus chargée ; proposez la version courante.
ResourceNotFound — utilisez search ou list-fiches pour proposer une URI proche.
RateLimitExceeded — implémentez un backoff exponentiel ; vérifiez que vos appels ne sont pas en boucle.

Voir aussi

Configuration — comment ajuster les limites de débit en mode HTTP.
FAQ — questions fréquentes sur le comportement du serveur.