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 — argumento inválido, não encontrado, escopo ou permissão insuficiente, um erro da rota — volta como uma resposta JSON-RPC bem-sucedida cujo resultado está marcado 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\": \"Execution not found\" } }" }]
} }

O vocabulário de code é o da API v1, sem mudança. Os que você mais vai encontrar:

code	Quando
VALIDATION_ERROR	Os argumentos falharam na validação — da própria tool (Invalid tool arguments.) ou da rota; os detalhes nomeiam os campos.
NOT_FOUND	Não existe esse registro, ele foi removido ou pertence a outra organização.
CONFLICT	Conflito de estado — por exemplo, nome de ambiente já usado.
IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_REQUEST_IN_PROGRESS	Veja Idempotência.
FEATURE_NOT_ENABLED	A Kobana não liberou essa operação para a organização.
ENTITLEMENT_REQUIRED	Disparo sem o Kadu no plano da organização.
MISSING_SECRETS, ENVIRONMENT_REQUIRED	Disparo com secrets exigidos sem valor no ambiente, ou sem ambiente válido. kadu_tasks_readiness_get confere antes.
COST_LIMIT_REACHED	A organização atingiu o teto mensal de custo.
RATE_LIMITED	O limite da rota foi atingido — veja Limite de Requisições.
USER_DECLINED	Na era 2026-07-28, você recusou ou cancelou a confirmação de uma tool destrutiva. Nada foi alterado.
confirmation_required	A tool é destrutiva, o cliente não consegue confirmar no chat e o token não tem uma pessoa da organização que possa abrir um link de aprovação. 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 (ou a aprovação por link) agora, então recusou a tool. Nada foi executado; tente de novo depois.

E os três que o próprio MCP acrescenta, porque são sobre autorização, não sobre o registro:

code	Quem resolve
insufficient_scope	O escopo do token não alcança a tool: o recurso não está no token, ou falta o nível que ela exige (write ou delete). Autorize de novo concedendo o acesso que faltou, ou use um token pessoal que alcance o recurso com o nível pedido.
insufficient_permission	Um administrador da organização, concedendo a permissão que o erro nomeia.
not_a_member	Autorizar o cliente de novo com uma conta que seja membro da organização — nenhuma permissão conserta isso.

Esses três 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.

Nem tudo que não executa é erro

• input_required. 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 cliente mostra a pergunta e reenvia a mesma chamada com a resposta.
• approval_required. Nos demais clientes, a mesma chamada volta, sem isError, status: "approval_required" com o link de aprovação. Mostre o link; não chame a tool de novo.

Os dois são o fluxo normal — 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 (HTTP 400)
-32600	Invalid request — não é um objeto JSON-RPC, é um array (batching não é suportado) ou o corpo passa de 1 MB
-32601	Method not found (HTTP 404 na era 2026-07-28)
-32602	Invalid params — tool ou prompt inexistente, name ausente, argumento de prompt inválido, resource sem permissão; 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
-32020	Header mismatch — na era 2026-07-28, um cabeçalho MCP não bate com o corpo (HTTP 400)
-32022	Unsupported protocol version (HTTP 400)

{ "jsonrpc": "2.0", "id": 3,
  "error": { "code": -32601, "message": "Method not found: tools/describe" } }

Erros de transporte

Recusas que acontecem antes da mensagem JSON-RPC ser lida são respostas HTTP comuns, com o envelope { "error": { "code", "message" } }: token ausente ou inválido, organização desconhecida, Origin fora da lista, limite de requisições, corpo grande demais, verificação do token indisponível. Estão listadas em Autenticação → Modos de falha.

Por que isError e não erro JSON-RPC

Um 404 numa execução 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 estruturada com a tool, a organização, o id do token, o tipo de token (fluxo OAuth ou pessoal), o status e a duração — nunca os argumentos, o token ou o corpo. O que a tool faz passa pela mesma rota da API, com os mesmos efeitos: um disparo vira uma execução como qualquer outra, com os mesmos eventos e webhooks. As aprovações por link ficam registradas em Configurações › Aprovações, com o que foi pedido, a decisão, quando e o resultado.