Formato de erro

Todo erro vem no mesmo envelope, com o status HTTP igual ao statusCode. O seu código decide pelo error.code; a message é para pessoas.

O envelope

Campos do envelope de erro
CampoO que é
successSempre false.
messageExplicação em português, para mostrar ou registrar. Pode mudar de texto: não compare.
statusCodeO mesmo status da resposta HTTP.
error.codeO código em inglês, em maiúsculas. Estável: é ele que o seu código compara.
error.detailsOpcional. Uma lista de campos (erros de validação) ou um objeto com o contexto do erro.

O que vem em details

  • VALIDATION_ERROR: uma lista de { path, message }. path aponta o campo no corpo, como /amount, /customer/document/number ou /destination/key.
  • Erros de regra trazem o dado que ajuda a corrigir: refundable em REFUND_EXCEEDS_REFUNDABLE, fee em AMOUNT_TOO_LOW, status em CHARGE_NOT_OPEN, chargeId em EXTERNAL_ID_CONFLICT de cobrança, beneficiaryId no CONFLICT de beneficiário repetido, retryAfterSeconds em RATE_LIMITED.
  • Sem nada a acrescentar, error vem só com code.

RISK_DECLINED nunca diz o motivo, de propósito. Erros internos (INTERNAL_ERROR) também não trazem detalhe: mande o X-Request-Id da resposta ao suporte.

Como reagir

Como reagir por status
StatusO que fazer
400 · 422O pedido não passou. Corrija o corpo, o cabeçalho ou o parâmetro apontado; repetir igual dá o mesmo erro.
401 · 403A chave, o escopo, o IP ou a situação da empresa. Não adianta repetir.
404NOT_FOUND: o recurso não existe nesta empresa e neste ambiente. ROUTE_NOT_FOUND: a rota não existe.
409Conflito com o estado de agora (já cancelado, já decidido, chave reaproveitada). Consulte o recurso antes de decidir.
429Limite de chamadas: espere error.details.retryAfterSeconds.
500 · 503Do nosso lado ou de um provedor. Repita depois, com a mesma Idempotency-Key: resposta 5xx não fica guardada. Em cobranças, mande também o externalId: se algo chegou a ser criado, a repetição devolve o existente.

Corpo que não é JSON válido responde 400 INVALID_JSON. Todos os códigos, com o status de cada um, estão em Códigos.