Erros
As falhas chegam por canais diferentes, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e explicar.
Erros de tool
Tudo sobre o que o chamador pode agir (validação do registro, registro não encontrado, estado que não permite a operação, escopo ou permissão insuficiente) volta como resposta JSON-RPC bem-sucedida, com o resultado marcado isError e o envelope de erro da Kobana como texto:
{ "jsonrpc": "2.0", "id": 2, "result": {
"isError": true,
"content": [{ "type": "text",
"text": "{ \"error\": { \"code\": \"unprocessable\", \"message\": \"Bank billet … (status paid) cannot be canceled in this status\" } }" }]
} }
O envelope vai só em content, nunca em structuredContent: um cliente que valida structuredContent contra o esquema de saída da tool esconderia o motivo do modelo.
code | Quando |
|---|---|
unprocessable | O estado do registro não permite a operação, ou um valor de argumento é inválido: cursor, fields, uid, operador de filtro |
validation_failed | O registro não passou na validação; a mensagem nomeia os campos |
not_found | O registro não existe nesta conta. Um uid de outra conta também é not_found |
user_declined | Na era 2026-07-28, você recusou ou cancelou a confirmação de uma tool destrutiva. Nada foi alterado |
tool_error | Outra falha de negócio; a mensagem diz qual |
E os de autorização, separados de propósito porque cada um se resolve com uma pessoa diferente:
code | Quem resolve |
|---|---|
insufficient_scope | Quem conectou o cliente: autorizar de novo com o recurso ou o nível de acesso que falta |
insufficient_permission | O administrador da conta: conceder a permissão de painel |
membership_inactive | O administrador da conta: reativar o usuário que autorizou o cliente |
product_not_enabled | A contratação: incluir o produto no plano da conta |
unauthorized | O token ou a conta não permitem a operação |
Um único "você não pode" não diria a quem pedir. Veja Autenticação.
Argumento fora do inputSchema
Os argumentos são validados contra o inputSchema da tool antes de ela rodar. Argumento não declarado, tipo errado, valor fora do enum (um sort_by que a listagem não aceita, um filtro que ela não declara) ou limit acima de 100 voltam como resultado isError com o texto Invalid arguments: … ou Missing required arguments: …, sem o envelope de erro da Kobana.
input_required não é erro
Na era 2026-07-28, o primeiro tools/call de uma tool destrutiva pode voltar resultType: "input_required", com um pedido de confirmação. É o fluxo normal: o cliente mostra a pergunta e reenvia a chamada com a sua resposta. Veja Confirmação de tools destrutivas.
Erros de protocolo
Uma mensagem malformada recebe um objeto de erro JSON-RPC, não um resultado:
| Código | Significado |
|---|---|
-32700 | O corpo não é JSON válido |
-32600 | Não é uma requisição JSON-RPC válida, ou é um array (batching não é suportado) |
-32601 | Método não encontrado |
-32602 | Parâmetros inválidos: tool ou prompt inexistente, prompt fora do seu alcance, argumento de prompt ausente; na era 2026-07-28, também resource não encontrado |
-32002 | Resource não encontrado, nas versões de 2025 |
-32020 | Na era 2026-07-28, cabeçalho que contradiz o corpo |
-32022 | Versão do protocolo não suportada; data lista as suportadas |
-32603 | Falha inesperada ao rodar a tool. A mensagem é genérica de propósito, e a falha é registrada do nosso lado |
{ "jsonrpc": "2.0", "id": 3,
"error": { "code": -32601, "message": "Method not found" } }
Erros de transporte
Recusas que acontecem antes de a mensagem JSON-RPC ser lida são respostas HTTP comuns. Token ausente ou inválido (401), conta bloqueada ou IP fora da allow list (403) e limite de requisições (429) vêm com o corpo de erro da API REST, em português. GET em / (405), corpo acima de 4 MiB (413) e Host ou Origin fora da allowlist (403) vêm como erro JSON-RPC -32600. Estão em Autenticação → Modos de falha HTTP e em Limite de requisições.
Por que isError e não erro JSON-RPC
Um boleto que não pode ser cancelado não é defeito do cliente MCP: é informação sobre o mundo, e o modelo precisa dela para se corrigir. Num erro de protocolo, o cliente a trataria como falha de transporte, esconderia o texto e, no melhor caso, tentaria de novo, idêntico. A regra é: se o chamador pode agir, é resultado; se a requisição está quebrada, é erro.
Observabilidade
Cada tools/call grava uma linha estruturada com a tool, a conta, o usuário, o token, o tipo de token, o resultado e a duração. Ao pedir ajuda ao suporte sobre uma chamada, informe a tool e o horário.