Lendo erros no protocolo
Decodifique códigos e mensagens de erro quando as chamadas falharem.
Lendo erros no protocolo é uma aula grátis de MCP Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de MCP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de MCP Academy inclui 4 aulas no total.
Quando as chamadas dão errado
Nem toda solicitação é bem-sucedida. Quando algo falha, o JSON-RPC envia um objeto de erro em vez de um resultado, e lê-lo é o caminho mais rápido para corrigir o problema.
O objeto de erro
Uma resposta de erro mantém o id da solicitação, mas troca o resultado por um objeto de erro que contém um código e uma mensagem.
{"jsonrpc": "2.0", "id": 3,
"error": {"code": -32601, "message": "Method not found"}}Os códigos são números
Cada erro contém um código numérico. Os códigos padrão do JSON-RPC são números negativos, e alguns aparecem repetidamente na comunicação.
Erro de análise: -32700
O código -32700 significa que o servidor nem sequer conseguiu analisar seu JSON. Geralmente, uma vírgula sobrando ou uma aspa quebrada danificou a própria mensagem.
{"error": {"code": -32700, "message": "Parse error"}}Método não encontrado: -32601
O código -32601 informa que o nome do método não existe. Verifique se há um erro de digitação ou se está usando um método que o servidor nunca anunciou, como toolz/list.
{"error": {"code": -32601, "message": "Method not found"}}Parâmetros inválidos: -32602
O código -32602 sinaliza parâmetros incorretos: um argumento ausente ou do tipo errado. O método existe, mas as entradas enviadas não são adequadas.
{"error": {"code": -32602, "message": "Invalid params"}}Erro interno: -32603
O código -32603 é o erro interno genérico do servidor. A solicitação estava correta, mas algo deu errado durante o processamento.
{"error": {"code": -32603, "message": "Internal error"}}Leia o campo de mensagem
O código informa a categoria; a mensagem conta o que aconteceu. Leia-a sempre, pois os servidores costumam acrescentar o campo exato ou o motivo da falha.
Dados opcionais para obter detalhes
Os erros também podem conter um campo data com detalhes estruturados adicionais, como o parâmetro que foi rejeitado. Isso é ótimo para depuração quando está presente.
{"error": {"code": -32602, "data": {"field": "a"}}}Erro de protocolo versus falha da ferramenta
Um erro de JSON-RPC significa que o próprio protocolo falhou. Uma ferramenta que é executada, mas retorna isError, continua sendo um resultado normal; portanto, não confunda os dois casos.
Um reflexo de depuração
Crie o hábito: leia o código para classificar, leia a mensagem para localizar e depois verifique os dados para identificar exatamente o culpado. A maioria dos problemas do MCP é descoberta rapidamente dessa forma.
Verificação rápida
Você enviou um método válido, mas com um argumento ausente. Qual código de erro corresponde a esse caso?
Recapitulação: decodificação de falhas
Agora você consegue ler falhas com fluência: um objeto de erro contém um código, uma mensagem e, às vezes, dados. O código classifica, a mensagem explica e os dados apontam precisamente para a causa.
Perguntas Frequentes
A aula “Lendo erros no protocolo” é grátis?
Sim — o texto completo de “Lendo erros no protocolo” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de MCP Academy, atualize para CoddyKit PRO. O curso de MCP Academy inclui 4 aulas no total.
O que vou aprender em “Lendo erros no protocolo”?
Decodifique códigos e mensagens de erro quando as chamadas falharem. Você pratica MCP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar MCP Academy?
Nenhuma experiência prévia é necessária. MCP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Lendo erros no protocolo”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de MCP Academy?
Sim. Cada aula de MCP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Solicitações, respostas e notificações
- Anatomia de uma chamada JSON-RPC
- O handshake de inicialização
- Lendo erros no protocolo