Erros
O formato das respostas de erro e o que cada status quer dizer.
Toda resposta de erro tem o mesmo formato:
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Revise os campos informados.",
"errors": [
{ "path": "customer.email", "message": "E-mail inválido." }
],
"path": "/api/v1/charges/pix",
"timestamp": "2026-10-04T15:30:00.000Z"
}code: para o seu código decidir o que fazer.message: em português, pode ser mostrada a quem opera o seu sistema.errors: só emVALIDATION_ERROR, com cada campo e o motivo.
Códigos
code | Quando |
|---|---|
VALIDATION_ERROR | Algum campo do corpo está faltando ou inválido. Veja errors. |
REQUEST_ERROR | O pedido não pôde ser atendido. A message diz o motivo (ex.: "CPF ou CNPJ do pagador inválido."). |
API_KEY_PERMISSION | A chave não tem a permissão da rota. Ajuste em Chaves de API. Veja Permissões. |
API_KEY_IP | A chamada veio de um IP que a chave não libera. Veja IPs permitidos. |
WITHDRAW_DAILY_LIMIT | O saque passaria do limite diário da chave. A message diz quanto ainda resta hoje. |
INTERNAL_ERROR | Falha do nosso lado. Tente de novo em instantes. |
Status HTTP
| Status | Quer dizer | O que fazer |
|---|---|---|
400 | Dados inválidos. | Corrija o pedido; repetir igual dá o mesmo erro. |
401 | Chave ausente, inválida ou revogada. | Confira o header x-api-key. |
403 | A chave não pode fazer isso: falta permissão, o IP não está liberado, o limite diário de saque acabou, a conta ainda não opera em produção ou a simulação foi feita com chave de produção. | Veja o code e a message. |
404 | Não encontrado nesta conta e neste modo. | Confira o id e se a chave é do mesmo modo (teste ou produção). |
429 | Muitas requisições. | Espere o tempo do header Retry-After. Veja Limites. |
5xx | Falha nossa ou da adquirente. | Tente de novo com a mesma idempotency-key. |