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 reagir.
Erros de tool
Tudo sobre o que o chamador pode agir — argumentos inválidos, registro não encontrado, escopo ou permissão insuficiente, um erro do endpoint — volta como uma resposta JSON-RPC bem-sucedida cujo resultado está marcado isError, carregando o envelope de erro como texto:
{ "jsonrpc": "2.0", "id": 2, "result": {
"isError": true,
"content": [{ "type": "text",
"text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Charge not found\" } }" }]
} }
Quando o erro vem do endpoint, o texto é o corpo original da API, { "error": { "code", "message", "details"? } }, com o vocabulário de code da API REST, sem mudança. Os que você mais vai encontrar:
code | Quando |
|---|---|
VALIDATION_ERROR | Os argumentos falharam na validação — da própria tool (um argumento desconhecido numa leitura, um tipo errado) ou do endpoint. details nomeia os campos. |
NOT_FOUND | Não existe esse registro, ou ele pertence a outra organização. |
CONFLICT | O registro conflita com outro, ou a transição de estado não é válida. Algumas transições têm código próprio — por exemplo, CHARGE_NOT_SETTLED ao pedir a carta de quitação de uma cobrança que não está paga. |
INSUFFICIENT_SCOPE / FORBIDDEN | A /v1 recusou a operação ao ser despachada — a checagem de escopo se repete lá. |
RATE_LIMITED | O balde do endpoint despachado se esgotou — veja Limite de requisições. |
USER_DECLINED | Na era 2026-07-28, o usuário recusou ou cancelou a confirmação de uma tool destrutiva. Nada foi alterado. |
confirmation_required | A tool é destrutiva e o cliente não consegue confirmar: está na era 2025 ou não declarou formulários de elicitation. Use um cliente na revisão 2026-07-28 com elicitation. Nada foi executado. |
confirmation_replayed | A confirmação enviada já tinha sido usada — cada uma roda uma chamada uma vez. Chame a tool de novo para ser perguntado outra vez. Nada foi executado. |
confirmation_unavailable | O servidor não conseguiu registrar a confirmação agora, então recusou a tool. Nada foi executado; tente de novo depois. |
E os quatro que o próprio MCP acrescenta, porque são sobre autorização, não sobre o recurso:
code | Quem resolve |
|---|---|
insufficient_scope | O escopo do token não alcança a tool: o recurso não está no token, ou falta acesso de escrita a ele. Use um token que alcance o recurso com o acesso pedido — no fluxo OAuth o acesso é só de leitura hoje; um token pessoal pode trazer escrita. |
insufficient_permission | Um admin da organização, concedendo a permissão que o erro nomeia. |
membership_inactive | Reativar a pessoa na organização — nenhuma permissão conserta um vínculo inativo. |
key_owner_not_member | A pessoa entrar uma vez no dashboard da Régua de Cobrança com a conta Kobana, ou pedir um convite para a organização. |
Esses quatro são separados de propósito: são conversas diferentes, com pessoas diferentes. Um erro único diria "você não pode" sem dizer a quem pedir. Veja Autenticação.
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 ao usuário. É o fluxo normal, não uma falha: o cliente mostra a pergunta e reenvia a mesma chamada com a 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 | Parse error — o corpo não é JSON válido |
-32600 | Invalid request — não é um objeto JSON-RPC, ou é um array (batching não é suportado) |
-32601 | Method not found |
-32602 | Invalid params — tool, prompt ou argumento de prompt inexistente; na era 2026-07-28, também resource não encontrado |
-32002 | Resource não encontrado — só na era 2025 (a 2026-07-28 usa -32602) |
-32603 | Internal error — falha inesperada ao rodar a tool |
{ "jsonrpc": "2.0", "id": 3,
"error": { "code": -32602, "message": "Unknown tool: dunning_charges_describe" } }
Erros de transporte
Recusas que acontecem antes da mensagem JSON-RPC ser lida são respostas HTTP comuns: token ausente ou inválido, versão de protocolo não suportada, cabeçalho que diverge do corpo, Origin não permitido, host errado, limite de requisições, corpo acima de 2 MB (413, com o erro JSON-RPC -32600 Request body too large). Estão listadas em Autenticação → Modos de falha.
Por que isError e não erro JSON-RPC
Um 404 numa cobrança não é um defeito do cliente MCP — é informação sobre o mundo, e o modelo do outro lado precisa dela para corrigir a si mesmo. Enterrá-la num erro de protocolo faria o cliente tratá-la como falha de transporte, esconder o texto e, no melhor caso, tentar de novo idêntico. Por isso a regra é: se o chamador pode agir, é resultado; se a requisição está quebrada, é erro.
Observabilidade
Cada tools/call escreve uma linha de log estruturado com a tool, a organização, o jti do token, o tipo do token (oauth ou personal), o vínculo da pessoa, o status e a duração. As escritas também aparecem na trilha de auditoria da organização, gravada pelo próprio endpoint despachado e atribuída ao token (api-token:<jti>) — o que um agente fez aparece ao lado do que uma pessoa fez, na mesma tela.