Operação

Erros e códigos HTTP

Toda resposta de erro segue o contrato único ErrorResponse. Registre o header X-Request-ID de cada requisição — ele é a chave para investigação com o suporte.

Contrato ErrorResponse

{
  "error": "validation_error",
  "options": {
    "message": "account, wallet or tax-identifier header is required"
  }
}

Códigos

HTTP	error	Como tratar
401	unauthorized	Token ausente, expirado ou inválido. Renove o access_token e repita.
403	forbidden	Integração não vinculada à conta referenciada nos headers de conta (account-id/wallet-id/tax-identifier), ou autorizador indisponível — nesse caso a resposta é fail-closed, por segurança.
404	not_found	Recurso não encontrado — txId, endToEndId, chave ou id inexistentes.
409	conflict	Conflito de negócio (ex.: cobrança já liquidada, chave duplicada, remoteId de transação já usado com dados diferentes). Não repita cegamente — inspecione.
422	validation_error	Payload inválido ou header de conta ausente — a mensagem real é 'account, wallet or tax-identifier header is required'. options.message aponta o campo problemático.
500	internal_error	Erro inesperado. Registre o X-Request-ID e contate o suporte.

409 nunca é retry silencioso

Um 409 sinaliza estado incompatível — cobrança já paga, chave duplicada, idempotência divergente. Inspecione a mensagem antes de tentar de novo.

403 x 422: como diferenciar

422: você não enviou nenhum header de conta (account-id/wallet-id/tax-identifier) ou o payload está inválido.
403: a referência veio, mas a sua integração não está vinculada àquela conta — ou o autorizador está indisponível (fail-closed). Ver Autorização por conta.

Rastreabilidade

Toda resposta traz X-Request-ID. Guarde-o em logs junto do seu account-id. Ao abrir chamado, envie os dois — a investigação é imediata.