Erros

Decida pelo código, não pela mensagem. A mensagem é uma frase em pt-BR pronta para a tela e pode mudar.

Formato

A API Keymatic responde com erro.codigo, erro.mensagem e, só em 422, erro.campos. O console e os fluxos de login usam detail.codigo e detail.mensagem, e validações podem trazer detail como lista. Não dependa de um único envelope entre as duas superfícies.

{
  "erro": {
    "codigo": "permissao_negada",
    "mensagem": "Frase em pt-BR para mostrar na tela.",
    "campos": [{ "campo": "nome", "mensagem": "..." }]
  }
}

API Keymatic

HTTP	Código	Quando acontece
401	`credencial_invalida`	Chave ausente, inválida, expirada ou revogada. Vem com WWW-Authenticate: Bearer.
402	`assinatura_api`	O plano não libera API Keymatic e MCP ou o pagamento não está em dia.
402	`conta_excedente`	A conta Instagram está fora das licenças do plano.
403	`permissao_negada`	A chave não tem a permissão exigida pela operação.
404	`nao_encontrado`	Recurso inexistente ou de outra conta. Objetos alheios sempre respondem 404.
409	`reconectar_instagram`	A autorização da Meta expirou ou foi retirada. Reconecte a conta no console.
409	`escopo_meta_ausente`	A conta não concedeu na Meta a permissão de que a operação precisa.
409	`chave_reutilizada`	Mesma Idempotency-Key com outro corpo.
409	`resposta_ja_reservada`	Já existe uma resposta reservada para este comentário ou mensagem no tenant, mesmo com outra chave.
409	`envio_iniciado`	O envio já começou e não pode mais ser alterado.
409	`code_invalido`	Code do onboarding repetido ou expirado. A chave emitida por ele foi revogada.
410	—	Replay da criação de uma regra que já foi apagada.
422	`entrada_invalida`	Corpo ou consulta fora do esquema. Em 422, campos lista cada problema.
428	`idempotency_key_ausente`	Escrita sem o cabeçalho Idempotency-Key.
429	`limite_tecnico`	Limite por IP ou de operações por minuto do tenant. Respeite Retry-After.
429	`limite_credencial`	Limite por minuto da chave.
429	`franquia_esgotada`	Franquia mensal de operações esgotada.
429	`publicacoes_esgotadas`	Franquia mensal de publicações esgotada.
502	`meta_indisponivel`	A Meta não respondeu. Leituras podem ser repetidas; escritas, só com a mesma Idempotency-Key.

Console e projetos

HTTP	Código	Quando acontece
401	`sessao_developers`	Sem sessão do console. Entre de novo.
401	`reautenticar`	A prova de login tem mais de 10 minutos. Volte ao login.
403	`developers_nao_ativado`	Developers ainda não foi ativado para este usuário. Aceite os termos e tente de novo.
422	`url_retorno_invalida`	URL de retorno do projeto fora das regras: HTTPS, exata, sem fragmento nem usuário.

Erros do retorno do onboarding hospedado estão em Onboarding hospedado.

No MCP

tools/call pode responder HTTP 200 com isError: true; quando disponível, structuredContent.codigo traz o mesmo código de recusa. Erro JSON-RPC, falha de transporte e operação com estado: erro são resultados diferentes.