Erros

Os clientes MCP podem receber três tipos de erro. Cada um chega em um lugar diferente, então trate cada um onde ele aparece.

Erros HTTP

A solicitação nem chega à ferramenta. O corpo é um erro JSON-RPC com o código -32000.

Status	Quando ocorre	O que fazer
401	Sem token, ou token inválido ou expirado	Siga o desafio WWW-Authenticate; consulte Autorização
405	GET ou DELETE no endpoint	Envie POST. O endpoint não tem fluxo SSE nem sessões
429	Um limite de cota foi excedido	Aguarde os segundos indicados em Retry-After; consulte Cotas

Erros de ferramenta

A ferramenta foi executada e falhou, ou foi recusada antes de ser executada. Nos dois casos, a resposta é um 200 normal com um resultado de tools/call que tem isError: true e o motivo em texto. Os erros que o SDK do MCP gera antes de o código da própria ferramenta rodar (argumentos que não correspondem ao esquema de entrada ou um nome de ferramenta desconhecido) chegam da mesma forma, com um texto que começa com MCP error -32602:. Eles continuam sendo resultados de ferramenta, não objetos error do JSON-RPC, então o cliente precisa verificar result.isError, e não error.code.

Um erro da própria ferramenta, para check_availability com { "domains": ["!!!"] }:

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

Um erro de validação da entrada, para compare_prices com { "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
}

Mensagem	Causa
MCP error -32602: Input validation error: Invalid arguments for tool <name>: …	Os argumentos não correspondem ao esquema de entrada da ferramenta: um campo ausente, um valor fora do intervalo, um domínio sem ponto. O texto termina com o campo em questão, por exemplo Too big: expected array to have <=20 items at domains
Invalid domain format	Não sobra nada da entrada depois que os caracteres que não podem aparecer em um nome de domínio são removidos, ou o nome tem um TLD que o NameBeta não conhece. Outros caracteres indevidos são removidos sem aviso, em vez de causarem erro; consulte check_availability
MCP error -32602: Tool <name> not found	O nome da ferramenta está escrito errado ou não existe
Qualquer outra mensagem	A consulta por trás da ferramenta falhou, por exemplo um servidor WHOIS ou DNS que não respondeu; pode funcionar se você tentar mais tarde

A página de cada ferramenta lista os erros específicos dela. Se uma chamada com falha ainda consome cota é explicado em Como as chamadas são contabilizadas.

Solicitações malformadas

Uma solicitação que o transporte MCP não consegue aceitar é rejeitada com um status 4xx antes da execução de qualquer ferramenta: por exemplo, 406 quando o cabeçalho Accept não inclui tanto application/json quanto text/event-stream, ou um erro de análise JSON-RPC (-32700) para um corpo que não é JSON-RPC válido. Solicitações JSON-RPC em lote (array) são rejeitadas com 400 e o erro JSON-RPC -32600, porque a especificação MCP abandonou o envio em lote na revisão de 18/06/2025; envie uma solicitação por POST. Corrija a solicitação em vez de repeti-la. Endpoint e transporte descreve as solicitações que o endpoint aceita.