Erreurs

Un client MCP peut rencontrer trois types d’erreurs. Elles n’arrivent pas au même endroit : traitez chacune là où elle apparaît.

Erreurs HTTP

La requête n’atteint jamais l’outil. Le corps de la réponse est une erreur JSON-RPC de code -32000.

Statut	Cas	Que faire
401	Aucun jeton, ou jeton invalide ou expiré	Suivez le challenge WWW-Authenticate ; consultez Autorisation
405	GET ou DELETE sur le point de terminaison	Envoyez un POST. Le point de terminaison n’a ni flux SSE ni sessions
429	Une limite de quota est dépassée	Attendez Retry-After secondes ; consultez Quotas

Erreurs d’outil

L’outil s’est exécuté et a échoué, ou il a été refusé avant de s’exécuter. Dans les deux cas, la réponse est un 200 normal, avec un résultat tools/call qui contient isError: true et la cause sous forme de texte. Les erreurs levées par le SDK MCP avant l’exécution du code de l’outil — des arguments qui ne respectent pas le schéma d’entrée, ou un nom d’outil inconnu — arrivent de la même façon, avec un texte qui commence par MCP error -32602:. Ce sont toujours des résultats d’outil, pas des objets error JSON-RPC : un client doit donc examiner result.isError, et non error.code.

Une erreur renvoyée par l’outil lui-même, pour check_availability avec { "domains": ["!!!"] } :

{
    "result": {
        "content": [{ "type": "text", "text": "Invalid domain format" }],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 4
}

Une erreur de validation des entrées, pour compare_prices avec { "domain": "kettlory" } :

{
    "result": {
        "content": [
            {
                "type": "text",
                "text": "MCP error -32602: Input validation error: Invalid arguments for tool compare_prices: A full domain name is required at domain"
            }
        ],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 1
}

Message	Cause
MCP error -32602: Input validation error: Invalid arguments for tool <name>: …	Les arguments ne respectent pas le schéma d’entrée de l’outil : champ manquant, valeur hors limites, domaine sans point. Le texte se termine par le nom du champ, par exemple Too big: expected array to have <=20 items at domains
Invalid domain format	Il ne reste rien de l’entrée une fois retirés les caractères qui ne peuvent pas figurer dans un nom de domaine, ou le nom porte un TLD que NameBeta ne connaît pas. Les autres caractères parasites sont retirés sans erreur au lieu d’être refusés ; consultez check_availability
MCP error -32602: Tool <name> not found	Le nom de l’outil est mal orthographié ou n’existe pas
Tout autre message	La consultation effectuée par l’outil a échoué, par exemple parce qu’un serveur WHOIS ou DNS n’a pas répondu ; elle peut réussir si vous réessayez plus tard

La page de chaque outil liste les erreurs qui lui sont propres. La section Comptabilisation des appels indique si un appel en échec est tout de même décompté de votre quota.

Requêtes mal formées

Une requête que le transport MCP ne peut pas accepter est refusée avec un statut 4xx avant l’exécution de tout outil : par exemple 406 lorsque l’en-tête Accept ne liste pas à la fois application/json et text/event-stream, ou une erreur d’analyse JSON-RPC (-32700) lorsque le corps n’est pas du JSON-RPC valide. Les requêtes JSON-RPC par lot (un tableau) sont refusées avec 400 et l’erreur JSON-RPC -32600, car la spécification MCP a supprimé les requêtes par lot dans sa révision du 18 juin 2025 ; envoyez une requête par POST. Corrigez la requête plutôt que de la renvoyer telle quelle. La page Point de terminaison et transport décrit les requêtes acceptées par le point de terminaison.