Tratamento de erros

Envelope (típico)

{
  "error": "descrição",
  "status": 400
}

TODO: chaves adicionais (código, correlation_id) se existirem na implementação — a origem mostra o mínimo.

Código	Significado	Ação
`200`	Sucesso em leitura / confirmação de webhook de entrada (parceiro)	Siga a operação.
`201`	Criação de recurso	Guarde o `id` e `externalId`.
`400`	Validação de payload	Corrija o corpo.
`401`	Autenticação	Conferir `Bearer` e validade/escopo do token.
`404`	Não encontrado	Conferir parâmetros, ambiente e o UUID usado.
`409`	Conflito (ex.: `externalId` duplicado)	Outro `externalId` ou recuperar o recurso existente.
`422`	Regra de negócio	Ajuste valor, prazo ou pré-condições.
`500`	Erro interno	Retentativas (com cuidado).

Tabela de troubleshooting: Códigos e sintomas.

5xx ou timeout em leitura (GET) ou leitura semelhante: use backoff exponencial com teto, sem martelar a API.
4xx (fora de rate limit) em escrita: não retente sem corrigir o payload.

TODO: rate limit (429, Retry-After) — a origem não cita; confirmar com a implementação do gateway.

Trate o webhook como at-least-once; valide a assinatura e deduplique.
Se a consulta mostrar o estado “à frente” do último evento processado, use o estado idempotente e reconcile logs.
Em PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED, use o guia de reconciliação operacional.

Após validar a assinatura, responda 2xx rapidamente. Erros 5xx do seu lado alimentam retentativas com backoff (fila, conforme a origem).
Handlers devem ser idempotentes.

O documento de origem cita: documentos podem ser mascarados em respostas de detalhe. Evite registrar dados sensíveis indevidamente.