Erros
As falhas chegam por dois canais diferentes, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e sobre o qual deve reagir.
Erros de tool
Tudo sobre o que quem chama pode agir — validação, não encontrado, escopo insuficiente, permissão insuficiente, erro do endpoint — volta como uma resposta JSON-RPC bem-sucedida cujo resultado é marcado com isError, carregando o envelope de erro da própria API como texto:
{ "jsonrpc": "2.0", "id": 2, "result": {
"isError": true,
"content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"not_found\", \"message\": \"not_found\" } }" }]
} }
O vocabulário de code é o da API REST, inalterado — veja Erros da API para a lista completa. Os códigos que você mais vai encontrar:
code | Quando |
|---|---|
validation_failed | Os argumentos falharam na validação do schema; details nomeia os campos |
not_found | Registro inexistente, ou pertencente a outro workspace |
conflict | external_id em uso, ou idempotency_key repetida com um body diferente |
unprocessable_entity | Violação de regra de negócio, p.ex. reprocessar um e-mail em status que não permite |
insufficient_scope | O token do cliente conectado não alcança a tool: o recurso não está no token, ou falta o acesso de escrita a ele. Pelo fluxo OAuth o acesso hoje é somente leitura; um token pessoal pode carregar escrita |
insufficient_permission | A pessoa não tem a permissão que a tool exige nesta organização |
method_not_allowed | A operação da tool não é suportada naquela rota |
user_declined | No protocolo 2026-07-28, o usuário recusou ou cancelou a confirmação de uma tool destrutiva. Nada mudou |
confirmation_required | Uma tool destrutiva chamada por um cliente que não consegue confirmá-la — era 2025, ou 2026-07-28 sem formulários de elicitation. Nada foi executado |
confirmation_replayed | Uma confirmação já usada foi enviada de novo. Nada foi executado; chame a tool sem requestState para perguntar de novo |
confirmation_unavailable | O servidor não conseguiu registrar a confirmação naquele momento. Nada foi executado; tente de novo mais tarde |
insufficient_scope e insufficient_permission são separados porque quem resolve cada um é diferente: o primeiro, quem for dono do cliente conectado e do token dele; o segundo, o administrador da organização, no dashboard.
input_required não é erro
No protocolo 2026-07-28, a primeira tools/call de uma tool destrutiva pode voltar com resultType: "input_required" e um pedido de confirmação ao usuário. Esse é o fluxo normal, não uma falha: o cliente mostra a pergunta e envia a mesma chamada de novo com a resposta. Veja Confirmação de tools destrutivas.
Erros de protocolo
Uma mensagem malformada recebe um objeto de erro JSON-RPC em vez de um resultado:
| Código | Significado |
|---|---|
-32700 | Parse error — o body não é JSON válido |
-32600 | Requisição inválida — não é um objeto JSON-RPC, ou é um batch em array (não suportado) |
-32601 | Método não encontrado |
-32602 | Params inválidos — tool, prompt ou argumento desconhecido, ou name ausente; no 2026-07-28, também resource não encontrado |
-32002 | Resource não encontrado — só nas revisões de 2025 (o 2026-07-28 usa -32602) |
-32020 | Header divergente — no 2026-07-28, um header MCP-Protocol-Version, Mcp-Method ou Mcp-Name que não bate com o body (HTTP 400) |
-32022 | Versão de protocolo não suportada — data.supported lista as suportadas (HTTP 400) |
-32603 | Erro interno — falha inesperada ao executar a tool |
Um body de requisição acima de 1 MB (1.048.576 bytes) é recusado com HTTP 413 e -32600 antes de qualquer execução — e, quando o Content-Length o declara, antes da autenticação:
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 1048576 bytes)" } }
{ "jsonrpc": "2.0", "id": 3, "error": { "code": -32601, "message": "Method not found: tools/describe" } }
Erros de transporte
Rejeições que acontecem antes de a mensagem JSON-RPC ser lida são respostas HTTP comuns com o envelope de erro da API — token ausente, token inválido ou emitido para outro recurso, origem não permitida, workspace não escolhido, pessoa que não é membro, limite de requisições, authorization server indisponível (503). Estão listadas em Autenticação.
Correlação
Toda resposta carrega um header X-Request-Id. Inclua-o ao relatar um problema para que o trace possa ser recuperado. Toda chamada de tool também é registrada no log de auditoria com o nome da tool, o workspace, o jti do token, se o token veio do fluxo OAuth ou é um token pessoal, a pessoa, o status resultante e a duração — nunca o endereço, o assunto ou o corpo de um e-mail.