Erros
A API INFI devolve erros com um corpo simples:
{ "error": "mensagem em português" }O status HTTP é a fonte primária para classificar o erro programaticamente. Não há campo code estável; baseie sua lógica em status + tipo de operação.
Sem requestId no corpo
Se precisar suporte para um caso, anote: data/hora UTC, endpoint, e o corpo enviado. A equipe da INFI correlaciona pelos logs internos.
Por status
400 Bad Request — payload inválido
Ocorre quando algum campo está faltando ou com tipo errado. Exemplos:
| Mensagem | Endpoint |
|---|---|
"amountCents deve ser inteiro ≥ 100 (R$1,00 mínimo)." | /v1/pix, /v1/withdraw |
"customer.name obrigatório." | /v1/pix |
"customer.document.number e customer.document.type obrigatórios." | /v1/pix |
"customer.document.type é obrigatório." | /v1/pix |
"customer.document.type deve ser 'cpf' ou 'cnpj'. Recebido: '<valor>'." | /v1/pix |
"customer.document.number deve ter 11 dígitos para cpf. Recebido: <N> dígitos." | /v1/pix |
"customer.document.number deve ter 14 dígitos para cnpj. Recebido: <N> dígitos." | /v1/pix |
"pixKey obrigatória." | /v1/withdraw |
"pixKeyType deve ser 'cpf', 'cnpj', 'email', 'phone' ou 'evp'. Recebido: '<valor>'." | /v1/withdraw |
"Valor abaixo do mínimo (R$ X,YY)." / "acima do máximo" | /v1/pix, /v1/withdraw |
"transactionId inválido." | /v1/transactions/:id |
401 Unauthorized — autenticação
| Mensagem |
|---|
"API key obrigatória. Use: Authorization: Bearer <key>" |
"API key inválida ou revogada." |
403 Forbidden — autorização
| Mensagem | Causa |
|---|---|
"Conta não está aprovada para uso da API." | KYC pendente. |
"Conta suspensa. Contate o suporte." | Conta bloqueada. |
"IP de origem não autorizado para esta chave." | IP fora da allowlist. |
"Tipo de chave PIX 'X' não autorizado para esta conta." | Restrição de configuração. |
"Saque com chave CPF só permitido para o CPF do responsável cadastrado." | Titularidade. |
"Saque com chave CNPJ só permitido para o CNPJ cadastrado da empresa." | Titularidade. |
404 Not Found
| Mensagem |
|---|
"Transação não encontrada." |
Transações de outros lojistas também retornam
404(não403) — para não vazar existência.
422 Unprocessable Entity
| Mensagem | Endpoint |
|---|---|
"Saldo insuficiente para realizar o saque." | /v1/withdraw |
429 Too Many Requests — rate limit
| Mensagem | Endpoint |
|---|---|
"Limite de requisições atingido. Tente em 1 hora." | /v1/pix |
"Limite de saques atingido." | /v1/withdraw |
Veja Rate limits.
502 Bad Gateway
| Mensagem | Significado |
|---|---|
"Erro ao comunicar com gateway. Tente novamente." | Falha transiente do provedor; pode retry. |
"Erro ao processar saque. O valor não foi debitado." | Falha do provedor com rollback feito. Pode retry. |
"Saque iniciado mas confirmação interrompida. Consulte /v1/transactions/<id>" | Operação concluída, resposta interrompida. Não retry. Consulte o transactionId. |
202 Accepted — saque indeterminado
{
"error": "Saque em verificação. Saldo debitado; status final em até 24h.",
"transactionId": "...",
"status": "failed_unknown"
}A INFI não sabe se o provedor concluiu ou não. Não reenvie. Aguarde reconciliação automática (até 24h) ou consulte. Veja Status / failed_unknown.
Estratégia de retry
| Cenário | Retry? |
|---|---|
Timeout de rede / 502 em POST /v1/pix | Sim, com externalRef para garantir idempotência. |
502 em POST /v1/withdraw com mensagem “valor não foi debitado” | Sim. |
502 em POST /v1/withdraw com mensagem “confirmação interrompida” | Não. Consulte /v1/transactions/:id. |
202 failed_unknown | Não. Aguarde. |
429 | Sim, após esperar (sugestão: 1h ou backoff exponencial com jitter). |
400, 401, 403, 422 | Não — corrija a causa antes. |
Sempre use externalRef em /v1/pix
Para retries seguros sem duplicar cobranças, sempre envie externalRef. Veja Idempotência.