Erros

A API usa códigos HTTP padrão e um código de erro estável no corpo da resposta, para que seu sistema possa tratar cada caso de forma programática.

Formato da resposta de erro

{
  "statusCode": 400,
  "error": "WITHDRAW_INSUFFICIENT_FUNDS",
  "message": "Saldo insuficiente para o saque solicitado."
}

Trate sempre pelo campo error (estável), não pelo message (pode mudar).

Códigos HTTP

Código	Significado
`400`	Requisição inválida (validação)
`401`	Token ausente/ inválido/ expirado
`403`	Sem permissão para o recurso
`404`	Recurso não encontrado
`409`	Conflito (ex.: idempotência)
`422`	Regra de negócio violada
`429`	Limite de requisições excedido
`500`	Erro interno

Catálogo de códigos de erro

Autenticação

Código	Quando ocorre
`AUTH_INVALID_TOKEN`	Token malformado ou inexistente
`AUTH_EXPIRED_TOKEN`	Token expirado
`AUTH_TOKEN_REVOKED`	Token revogado no painel
`AUTH_INSUFFICIENT_PERMISSIONS`	Token sem permissão para a operação

Cobranças (Pix)

Código	Quando ocorre
`PAYMENT_NOT_FOUND`	Cobrança inexistente
`PAYMENT_CREATION_FAILED`	Falha ao criar a cobrança
`PAYMENT_ALREADY_PROCESSED`	Cobrança já processada
`PAYMENT_EXPIRED`	Cobrança expirada
`PAYMENT_INVALID_AMOUNT`	Valor inválido

Saques

Código	Quando ocorre
`WITHDRAW_INSUFFICIENT_FUNDS`	Saldo insuficiente
`WITHDRAW_BELOW_MINIMUM`	Abaixo do mínimo permitido
`WITHDRAW_ABOVE_MAXIMUM`	Acima do máximo permitido
`WITHDRAW_PROVIDER_ERROR`	Falha ao liquidar o saque
`WITHDRAW_NOT_FOUND`	Saque inexistente

Validação

Código	Quando ocorre
`VALIDATION_INVALID_PIX_KEY`	Chave Pix inválida
`VALIDATION_INVALID_DOCUMENT`	CPF/CNPJ inválido
`VALIDATION_INVALID_QR_CODE`	QR Code inválido
`VALIDATION_MISSING_REQUIRED_FIELD`	Campo obrigatório ausente
`VALIDATION_INVALID_FORMAT`	Formato inválido

Merchants

Código	Quando ocorre
`MERCHANT_NOT_FOUND`	Merchant inexistente
`MERCHANT_INSUFFICIENT_FUNDS`	Saldo do merchant insuficiente

Infraestrutura

Código	Quando ocorre
`PROVIDER_UNAVAILABLE`	Serviço de liquidação temporariamente indisponível
`PROVIDER_TIMEOUT`	Liquidação não respondeu a tempo
`PROVIDER_INVALID_RESPONSE`	Resposta inesperada na liquidação
`RATE_LIMIT_EXCEEDED`	Excesso de requisições
`IDEMPOTENCY_CONFLICT`	Mesma `Idempotency-Key` com payload diferente
`INTERNAL_ERROR`	Erro interno

Webhooks

Código	Quando ocorre
`WEBHOOK_INVALID_SIGNATURE`	Assinatura do webhook inválida
`WEBHOOK_PROCESSING_FAILED`	Falha ao processar o evento

Como tratar (recomendação)

429 / PROVIDER_TIMEOUT / PROVIDER_UNAVAILABLE → retry com backoff.
WITHDRAW_INSUFFICIENT_FUNDS / *_NOT_FOUND → não faça retry; trate na lógica.
IDEMPOTENCY_CONFLICT → gere uma nova Idempotency-Key para a nova intenção.

Convenções

Changelog