Estrutura de erro

Todas as respostas de erro da API seguem um formato JSON padronizado, com código, mensagem e opcionalmente detalhes de validação ou metadados.

Exemplo genérico

JSON

{
  "code": "INVALID_REQUEST",
  "message": "Os dados enviados são inválidos.",
  "details": {
    "field": "amount",
    "reason": "Deve ser um número positivo em centavos."
  },
  "requestId": "req_abc123"
}

Campos

code — Código do erro (ex.: INVALID_API_KEY, RATE_LIMIT_EXCEEDED). Use para lógica programática.
message — Mensagem legível para exibição ou log.
details — (Opcional) Objeto com campo e motivo de validação, ou informações adicionais.
requestId — (Opcional) Identificador da requisição para suporte.

Exemplo de validação (400)

JSON

{
  "code": "INVALID_REQUEST",
  "message": "Erro de validação.",
  "details": [
    { "field": "customerDocument", "reason": "CPF inválido." },
    { "field": "amount", "reason": "Deve ser maior que zero." }
  ]
}

Exemplo de rate limit (429)

JSON

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de requisições excedido. Tente novamente após o tempo indicado no header Retry-After."
}