Formato de erro
Códigos HTTP
| Status | Significado | Ação recomendada |
|---|---|---|
200 | Sucesso | — |
201 | Criado | Recurso criado com sucesso |
400 | Bad Request | Verifique os parametros enviados |
401 | Unauthorized | Token ausente, expirado ou invalido |
403 | Forbidden | Sem permissão para este recurso |
404 | Not Found | Recurso não encontrado |
409 | Conflict | Idempotency-Key reutilizada com body diferente |
422 | Unprocessable Entity | Validação falhou (campos obrigatórios ausentes) |
429 | Too Many Requests | Rate limit excedido — aguarde Retry-After |
500 | Internal Server Error | Erro interno — contate o suporte |
503 | Service Unavailable | Serviço temporariamente indisponível |
Erros comuns
Autenticação
| Erro | Causa | Solucao |
|---|---|---|
UNAUTHORIZED | Token ausente ou expirado | Envie um token valido no header Authorization |
INVALID_API_KEY | API Key revogada ou inexistente | Verifique a key no dashboard |
2FA_REQUIRED | Login exige código 2FA | Inclua twoFactorCode no body |
Transações
| Erro | Causa | Solucao |
|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | Header Idempotency-Key ausente | Envie um UUID v4 no header |
IDEMPOTENCY_CONFLICT | Mesma key com body diferente | Use uma nova key para operação diferente |
INVALID_PAYMENT_METHOD | Método de pagamento invalido | Use PIX, BOLETO ou CARD |
AMOUNT_TOO_LOW | Valor abaixo do mínimo | Envie valor >= 100 (R$ 1,00) |
SELLER_INACTIVE | Seller bloqueado ou inativo | Verifique o status do seller no dashboard |
ACQUIRER_UNAVAILABLE | Provedor de pagamento fora | Tente novamente em alguns minutos |
Saques
| Erro | Causa | Solucao |
|---|---|---|
INSUFFICIENT_BALANCE | Saldo insuficiente | Verifique saldo disponível via GET /balance-statement |
WITHDRAWAL_LIMIT_EXCEEDED | Limite diário excedido | Aguarde o próximo dia útil |
INVALID_PIX_KEY | Chave PIX invalida | Verifique o formato da chave |