Pour commencer
Codes d'erreur
Une erreur de Prescriptio dit ce qui s'est passé et quoi faire : le connecteur MCP renvoie une erreur JSON-RPC quand l'appel est impossible, et une erreur métier lisible par le modèle quand l'action n'a pas abouti ; l'API REST renvoie les mêmes cas en codes HTTP.
Sur cette page
Un message d'erreur n'est jamais une donnée : il ne se recopie pas comme un fait.
Les deux familles d'erreurs
- Erreur JSON-RPC (champ
error) : l'appel n'a pas pu avoir lieu (requête illisible, outil inconnu, portée absente, quota, dépendance indisponible). - Erreur d'outil (
result.isError: true) : l'outil a été appelé, mais l'action n'a pas abouti. Un argument absent ou hors schéma arrive ainsi, avec un message en français qui nomme l'argument et dit quoi corriger : le modèle le lit et se reprend.
Connecteur MCP
| Code | Quand | Que faire |
|---|---|---|
-32700 | Le corps n'est pas un JSON lisible | Corriger le JSON envoyé |
-32600 | Requête invalide : envoi groupé, champ method absent, corps de plus de 3 Mio | Un appel par requête, un corps plus léger |
-32001 | Jeton absent, expiré ou révoqué (réponse HTTP 401 avec WWW-Authenticate) | Relancer l'autorisation OAuth |
-32601 | La méthode ou l'outil demandé n'existe pas à cette adresse | Appeler tools/list ; ne jamais deviner un nom |
-32003 | La portée OAuth manque à l'autorisation | Reconnecter en acceptant mcp:read, ou mcp:write pour écrire ; le refus nomme la portée, jamais une offre |
-32004 | Le quota par minute ou le quota journalier est atteint | Lire le message : attendre le délai indiqué, ne jamais boucler |
-32603 | Une dépendance ne répond pas | Réessayer plus tard ; ne pas rejouer une écriture sans vérifier qu'elle n'a pas eu lieu |
-32602 ne sert qu'à la lecture d'une ressource (resources/read) : adresse absente, inconnue ou indisponible. Un appel d'outil ne le rend jamais.
API REST
Le corps d'une erreur porte error.code, error.message, error.retry_after_seconds quand le délai est connu, et api_contract_version.
| HTTP | error.code | Que faire |
|---|---|---|
400 | invalid_arguments, invalid_cursor | Corriger l'argument ; reprendre le curseur tel qu'il a été rendu |
400 | invalid_json, invalid_body | Envoyer un corps JSON lisible |
401 | unauthenticated | Obtenir un nouveau jeton |
403 | insufficient_scope | Redemander l'autorisation avec la portée nommée |
403 | access_denied, user_required, organization_required, role_denied | L'action exige un utilisateur, une organisation ou un rôle que le jeton n'a pas |
403 | origin_denied | L'appel vient d'un navigateur dont l'origine n'est pas autorisée |
404 | not_found | L'opération ou l'objet est introuvable dans votre espace |
405 | method_not_allowed | Appeler l'opération en POST |
408 | invalid_body | Le corps n'est pas arrivé en 30 secondes : renvoyer |
409 | conflict | L'action entre en conflit avec l'état de l'objet |
413 | invalid_body | Alléger le corps : 3 Mio au plus |
415 | unsupported_media_type | Envoyer Content-Type: application/json |
429 | quota_exceeded | Attendre Retry-After quand il est donné ; lire le message |
503 | unavailable, quota_unavailable | Réessayer plus tard |
504 | timeout | L'opération a dépassé 35 secondes ; vérifier avant de rejouer une écriture |
{
"error": {
"code": "quota_exceeded",
"message": "<message en français>",
"retry_after_seconds": 60
},
"api_contract_version": "3.0.0"
}Les trois refus de quota
« Quota par minute atteint »
Un frein passager, au-delà de 5 appels par minute (30 pour un abonné). Attendez une minute et reprenez, un appel à la fois. L'abonnement n'est pas la réponse.
« Quota journalier atteint »
Le plafond des 24 heures glissantes (100 appels, ou 5 000 pour un abonné). L'abonnement relève ce plafond ; l'analyse du rapport de marque lui est aussi réservée. Les outils d'aide et d'abonnement restent soumis au quota d'appels : s'il est épuisé, ouvrez directement Paramètres › Abonnement (s'ouvre dans un nouvel onglet), ou attendez que la fenêtre se libère.
« Quota de consultation atteint »
Les dossiers ouverts aujourd'hui (5, ou 500 pour un abonné). Le compteur repart à minuit, heure de Paris, et un dossier déjà ouvert se relit sans compter. Chercher n'entre pas dans ce compte, seulement dans le quota d'appels ; l'abonnement relève ce plafond.
Sur /api/mcp, les deux premiers refus arrivent généralement en erreur -32004 ; le troisième arrive comme une erreur d'outil (isError), puisque c'est l'outil de lecture qui compte les dossiers. Un outil passant par le traitement des intégrations peut aussi rendre son refus dans isError. Le profil /api/mcp/connectors rend les erreurs de ses opérations dans isError, avec le détail dans _meta["prescriptio/error"]. Par l'API REST, les trois rendent 429 quota_exceeded.
Tester un jeton
GET /api/mcp/v1/me répond sans donnée personnelle : le jeton est-il valable, avec quelle offre et quelles portées.
curl -sS https://prescriptio.fr/api/mcp/v1/me -H 'Authorization: Bearer <jeton>'{ "authenticated": true, "tier": "<offre>", "scope": "<portées>" }Un message d'erreur n'est jamais une donnée : ne le recopiez pas comme un fait, et n'inventez pas un identifiant ou une adresse qu'il ne contient pas.