Erros: o que aconteceu e como agir

Erro JSON da API#

O HTTP indica a categoria; error.code permite tratamento automático; error.message explica o problema em português.

json

{
  "error": {
    "code": "resource_not_found",
    "message": "Recurso não encontrado.",
    "details": null,
    "request_id": "38ffbe83-464e-411a-99da-cf5018d535d1"
  }
}

Guarde o request_id para suporte. Não envie a API Key, o cabeçalho de autorização nem os dados do contato. Não dependa do texto da mensagem para decidir a ação: use o código.

Guia de recuperação#

HTTP / código	Ação recomendada
`400 invalid_request`, `invalid_json`	Corrija formato, campos, datas ou IDs antes de repetir.
`400 invalid_cursor`	Use o cursor retornado pela operação, sem modificá-lo.
`400 invalid_idempotency_key`	Informe uma chave idempotente válida; preserve-a nos retries da mesma ação.
`400 invalid_expiration`, `invalid_scope`, `duplicate_scope`	Revise validade e permissões ao criar uma API Key.
`401 invalid_api_key`	Confira a credencial no cofre e o formato Bearer; não tente adivinhar chaves.
`401 revoked_api_key`, `expired_api_key`	Substitua a chave na integração. A antiga não voltará a funcionar.
`403 insufficient_scope`	Crie uma chave substituta com a permissão necessária; altere a integração e só então revogue a antiga.
`403 key_management_forbidden`	A gestão de chaves exige o usuário proprietário da clínica.
`404 route_not_found`	Confira método, versão e caminho na referência.
`404 resource_not_found`	Recurso indisponível para essa chave. Ausência e outra clínica têm a mesma resposta.
`405 method_not_allowed`	Use um método publicado. A API não oferece CORS para uso no navegador.
`409 version_conflict`	Leia a versão atual e reconcilie a mudança antes de criar uma nova operação.
`409 idempotency_conflict`	Pare e confira método, caminho, corpo e chave da tentativa original; não gere outra chave automaticamente.
`409 idempotency_in_progress`	Aguarde e repita com a mesma chave e corpo. Se persistir, peça suporte.
`409 duplicate_contact`, `duplicate_tag`, `duplicate_service`, `user_already_exists`	Consulte o registro existente antes de tentar criar outro.
`409 contact_has_history`, `stage_not_empty`, `tag_in_use`, `last_clinic_owner`	A ação foi bloqueada para preservar histórico ou vínculos. Revise a regra do recurso.
`409 duplicate_followup_sequence`, `tracking_link_conflict`, `active_key_limit_reached`	Corrija a sequência, identificação do link ou quantidade de chaves ativas.
`413 payload_too_large`	Reduza o corpo ao limite documentado; repetir o mesmo corpo não resolve.
`415 unsupported_media_type`	Envie `Content-Type: application/json`.
`422 business_rule_violation`	Revise a regra de negócio indicada; não faça retry automático.
`429 rate_limit_exceeded`	Aguarde `Retry-After`; aumente progressivamente o intervalo, com pequena variação aleatória.
`500 internal_error`, `database_operation_failed`, `invalid_database_response`	Guarde o request ID. Em escrita, preserve corpo e chave e não assuma que a ação falhou antes de gravar.
`500 sender_not_configured`, `502 delivery_unknown`	Retorno automático indisponível ou entrega incerta: interrompa a automação e peça revisão humana.
`502 upstream_unavailable`	Falha temporária de comunicação; em escrita, mantenha a mesma chave idempotente.

Recebi 403 ou HTML em vez de JSON#

O bloqueio pode ocorrer na camada de proteção antes de chegar à API. Um 403 sozinho não prova falta de scope, chave inválida ou bloqueio por assinatura do cliente HTTP.

Confira Content-Type, presença de X-Request-Id e, quando existir, o identificador CF-Ray. Encaminhe ao suporte horário, domínio, rota sem dados pessoais e esses identificadores. Não insista em loop, não disfarce o cliente para contornar a proteção e não desative regras de segurança por conta própria.

Erros no MCP#

Falhas de transporte/autenticação usam status HTTP. Uma chamada de ferramenta pode retornar HTTP 200 com result.isError: true: leia o erro dentro de result.content. Erros de protocolo usam error.code numérico no envelope JSON-RPC. HTTP 200, sozinho, não confirma que uma venda foi registrada.

Veja tentativas seguras e idempotência antes de automatizar escritas.