Toda resposta de erro segue o mesmo envelope:
{ "error": { "code": "INSUFFICIENT_FUNDS", "message": "saldo insuficiente", "details": { "available_cents": 6555 } } }
code é estável (use-o no seu código; a message pode mudar).
| Código | HTTP | Quando |
|---|
VALIDATION_ERROR | 400 | payload inválido (campos faltando/errados) |
UNAUTHORIZED | 401 | chave ausente ou inválida |
KEY_REVOKED | 401 | chave de API revogada |
FORBIDDEN | 403 | sem permissão para a ação |
TEST_ONLY | 403 | rota de simulação chamada com chave live |
ACCOUNT_SUSPENDED | 403 | conta suspensa/bloqueada |
NOT_FOUND | 404 | recurso inexistente (ou fora do seu escopo) |
DUPLICATE_EXTERNAL_ID | 409 | external_id já usado (retorna o recurso em details) |
INSUFFICIENT_FUNDS | 422 | saldo insuficiente para o saque |
RATE_BELOW_FLOOR | 422 | taxa abaixo do piso permitido |
INVALID_PIX_KEY | 422 | chave PIX inválida |
AMOUNT_OUT_OF_RANGE | 422 | valor fora dos limites |
PROVIDER_ERROR | 502 | falha do provedor ao criar a cobrança |
PROVIDER_TIMEOUT | 504 | timeout do provedor — não refaça saque sem consultar |
Em saques, um 504 PROVIDER_TIMEOUT não significa que o saque falhou — o PIX pode ter
saído. Aguarde o webhook antes de tentar de novo.