Respostas de erro

Vale para toda a API. Os erros chegam em um destes dois formatos:

{ "status": "error", "message": "descricao do erro" }
{ "detail": "descricao do erro", "code": "codigo_do_erro" }

HTTP	Quando acontece	Repetir a chamada?
400	Campo obrigatório ausente, formato incorreto, valor inválido ou campo não editável	Não — corrija o pedido
401	Token ausente, expirado ou inválido	Depois de renovar o token
403	O recurso pertence a outro lojista	Não
404	Recurso não encontrado — a mensagem diz qual (Subscription not found, Charge not found, Online sale not found)	Não
409	Operação incompatível com o estado do recurso	Não — consulte o recurso
422	Cartão recusado pelo adquirente na tokenização. code: "CARD_REJECTED" e motivo em denial	Com outro cartão
429	Tentativas de login demais. Ver Autenticação	Depois de ~1 minuto
502	Falha de comunicação com o adquirente — timeout, rede ou erro interno dele. Não é recusa de cartão	Sim

observação

400 é sobre o seu pedido, 409 é sobre o recurso, 422 é sobre o cartão, 502 é sobre o adquirente. 502 é a única resposta em que vale repetir a mesma chamada.

As mensagens de 400 dizem o problema em texto direto (por exemplo, endDate precedes nextDueDate ou payerName excede 100 caracteres), sem prefixos internos. Use o código HTTP para decidir e a mensagem para registrar.

Sobre gateway_error

Alguns 502 da pré-captura trazem gateway_error com o retorno bruto do adquirente, para diagnóstico. O formato desse campo não é contrato — pode mudar sem aviso. Não faça parse dele: registre o trace_id e trate como 502.

Erros de validação trazem a lista dos campos:

{ "status": "error", "message": "Campos obrigatórios ausentes", "missing": ["cvv", "cardHolder"] }
{ "status": "error", "message": "Campos não editáveis", "rejectedFields": ["payerName"] }

Cartão recusado (422):

{
  "status": "error",
  "code": "CARD_REJECTED",
  "message": "Card rejected",
  "denial": { "code": "57", "message": "Card Expired" }
}

O denial.message vem sempre preenchido. Se o adquirente não informar motivo, vem "Cartão recusado pelo adquirente sem motivo informado".

Rastreando uma chamada. Toda resposta traz o cabeçalho X-Trace-Id, e os erros repetem o mesmo valor no corpo:

{
  "status": "error",
  "message": "Venda não está pré-capturada",
  "trace_id": "aabbccdd0102030405060708090a0b0c"
}

Ao abrir um chamado, informe o trace_id.