Erros

Os erros seguem a RFC 9457 (application/problem+json). title e detail vêm em português, para mostrar a pessoas; code é estável e é ele que o seu código deve usar para decidir.

{
  "type": "https://docs.exemplo.com.br/erros/validation-error",
  "title": "Dados inválidos",
  "status": 400,
  "detail": "Um ou mais campos não passaram na validação.",
  "code": "validation-error",
  "request_id": "req_01J9Z5…",
  "errors": [{ "field": "amount", "code": "invalid-format", "message": "Informe o valor com duas casas decimais e ponto, ex.: \"149.90\"." }]
}

Informe o request_id ao suporte: com ele localizamos a chamada.

Códigos

code	HTTP	O que significa	O que fazer
validation-error	400 / 422	Campo inválido (veja errors)	Corrija e envie de novo
unauthorized	401	Chave ausente, inválida, expirada ou revogada	Confira a chave
insufficient-scope	403	A chave não tem o escopo	Crie chave com o escopo
ip-not-allowed	403	IP fora da lista da chave	Ajuste a lista
unit-suspended / unit-not-active	403	Unidade sem recebimento	Fale com o seu gerente
access-blocked	403	Acesso bloqueado por segurança	Não repita; fale com o seu gerente
amount-above-limit	403	Valor acima do permitido por cobrança	Fale com o seu gerente
not-found	404	Não existe (ou é de outra unidade)	—
idempotency-key-required	400	POST sem Idempotency-Key	Envie o cabeçalho
idempotency-key-in-progress	409	A primeira requisição ainda roda	Repita em instantes
idempotency-key-reused	422	Mesma chave, corpo diferente	Use outra chave
external-ref-already-used	409	external_ref repetido	Consulte a cobrança existente
charge-not-active	409	A cobrança não está ativa	—
payment-not-unmatched	409	O pagamento não está "sem cobrança"	—
refund-exceeds-available	422	Devolução acima do disponível	Reduza o valor
refund-in-progress	409	Já há devolução em processamento	Aguarde
payment-under-med-block	409	Pagamento em bloqueio MED	Aguarde a análise
payment-fully-refunded	409	Já devolvido por inteiro	—
payment-link-unavailable	409	Link desativado, expirado ou esgotado	—
webhook-url-not-allowed	422	URL de webhook recusada (só https público)	Use outra URL
rate-limited	429	Muitas requisições	Espere Retry-After
quota-exceeded	429	Cota diária de cobranças atingida	Tente amanhã ou fale com o gerente
bank-unavailable	503	Banco indisponível	Repita com a mesma Idempotency-Key
internal-error	500	Erro nosso	Repita com a mesma Idempotency-Key