Errores

Los clientes MCP pueden recibir tres tipos de error. Llegan por vías distintas, así que trata cada uno donde aparece.

Errores HTTP

La solicitud no llega a la herramienta. El cuerpo es un error JSON-RPC con el código -32000.

Estado	Cuándo	Qué hacer
401	No hay token, o el token no es válido o ha caducado	Sigue el desafío WWW-Authenticate; consulta Autorización
405	GET o DELETE sobre el endpoint	Envía POST. El endpoint no tiene flujo SSE ni sesiones
429	Se ha superado un límite de cuota	Espera los segundos de Retry-After; consulta Cuotas

Errores de herramienta

La herramienta se ejecutó y falló, o se rechazó antes de ejecutarse. En ambos casos la respuesta es un 200 normal con un resultado de tools/call que tiene isError: true y el motivo en forma de texto. Los errores que lanza el SDK de MCP antes de que se ejecute el código de la herramienta (argumentos que no cumplen el esquema de entrada o un nombre de herramienta desconocido) llegan de la misma forma, con un texto que empieza por MCP error -32602:. Siguen siendo resultados de herramienta, no objetos error de JSON-RPC, así que el cliente tiene que mirar result.isError y no error.code.

Un error de la propia herramienta, para check_availability con { "domains": ["!!!"] }:

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

Un error de validación de entrada, para compare_prices con { "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
}

Mensaje	Causa
MCP error -32602: Input validation error: Invalid arguments for tool <name>: …	Los argumentos no cumplen el esquema de entrada de la herramienta: falta un campo, un valor está fuera de rango, un dominio no tiene punto. El texto termina con el campo afectado, por ejemplo Too big: expected array to have <=20 items at domains
Invalid domain format	No queda nada de la entrada tras eliminar los caracteres que no pueden aparecer en un nombre de dominio, o el nombre tiene un TLD que NameBeta no conoce. Los demás caracteres sobrantes se eliminan sin avisar en lugar de rechazarse; consulta check_availability
MCP error -32602: Tool <name> not found	El nombre de la herramienta está mal escrito o no existe
Cualquier otro mensaje	Falló la consulta en la que se basa la herramienta, por ejemplo un servidor WHOIS o DNS que no respondió; puede funcionar si se reintenta más tarde

La página de cada herramienta enumera los errores propios de ella. Si una llamada fallida consume o no cuota se explica en Cómo se contabilizan las llamadas.

Solicitudes mal formadas

Una solicitud que el transporte MCP no puede aceptar se rechaza con un estado 4xx antes de que se ejecute ninguna herramienta: por ejemplo, 406 cuando la cabecera Accept no incluye tanto application/json como text/event-stream, o un error de análisis JSON-RPC (-32700) cuando el cuerpo no es JSON-RPC válido. Las solicitudes JSON-RPC por lotes (un array) se rechazan con 400 y el error JSON-RPC -32600, ya que la especificación MCP eliminó los lotes en su revisión del 18 de junio de 2025; envía una solicitud por POST. Corrige la solicitud en lugar de reintentarla. Endpoint y transporte describe las solicitudes que acepta el endpoint.