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 — validação, não encontrado, escopo insuficiente, 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 da própria API como texto:

{ "jsonrpc": "2.0", "id": 2, "result": {
  "isError": true,
  "content": [{ "type": "text",
    "text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Portal user not found\" } }" }]
} }

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

code	Quando
VALIDATION_ERROR	Os argumentos falharam na validação do endpoint; os detalhes nomeiam os campos.
NOT_FOUND	Não existe esse registro, ou ele pertence a outra organização.
CONFLICT / DUPLICATE_ERROR	external_id já em uso, ou uma chave de negócio duplicada.
BAD_REQUEST	Regra de negócio violada — por exemplo, reenviar o convite de um usuário do portal que já está ativo.
FORBIDDEN	A operação não é permitida para este recurso no estado em que ele está.
EXTERNAL_SERVICE_ERROR	Um serviço externo do qual a operação depende recusou ou não respondeu.
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 que autorizou o cliente — nenhuma permissão conserta um vínculo morto.
key_owner_not_member	Autorizar o cliente de novo com uma conta que seja membro da 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 inexistente, name ausente; 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": -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 de erro da API: token ausente ou inválido, versão de protocolo não suportada, Origin fora da allowlist, limite de requisições, corpo acima de 1 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 num usuário do portal 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 estruturada com a tool, a organização, o token, 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 à pessoa que autorizou o cliente — o que um agente fez aparece ao lado do que uma pessoa fez, na mesma tela.