Errors
The INFI API returns errors with a simple body:
{ "error": "mensagem em português" }The HTTP status is the primary source for classifying the error programmatically. There is no stable code field; base your logic on status + operation type.
If you need support for a case, take note of: UTC date/time, endpoint, and the request body sent. The INFI team correlates via internal logs.
By status
400 Bad Request — invalid payload
Occurs when a field is missing or has the wrong type. Examples:
| Message | 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: '<value>'." | /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: '<value>'." | /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 — authentication
| Message |
|---|
"API key obrigatória. Use: Authorization: Bearer <key>" |
"API key inválida ou revogada." |
403 Forbidden — authorization
| Message | Cause |
|---|---|
"Conta não está aprovada para uso da API." | KYC pending. |
"Conta suspensa. Contate o suporte." | Account blocked. |
"IP de origem não autorizado para esta chave." | IP outside the allowlist. |
"Tipo de chave PIX 'X' não autorizado para esta conta." | Configuration restriction. |
"Saque com chave CPF só permitido para o CPF do responsável cadastrado." | Holder constraint. |
"Saque com chave CNPJ só permitido para o CNPJ cadastrado da empresa." | Holder constraint. |
404 Not Found
| Message |
|---|
"Transação não encontrada." |
Transactions from other merchants also return
404(not403) — so existence is not leaked.
422 Unprocessable Entity
| Message | Endpoint |
|---|---|
"Saldo insuficiente para realizar o saque." | /v1/withdraw |
429 Too Many Requests — rate limit
| Message | Endpoint |
|---|---|
"Limite de requisições atingido. Tente em 1 hora." | /v1/pix |
"Limite de saques atingido." | /v1/withdraw |
See Rate limits.
502 Bad Gateway
| Message | Meaning |
|---|---|
"Erro ao comunicar com gateway. Tente novamente." | Transient provider failure; may retry. |
"Erro ao processar saque. O valor não foi debitado." | Provider failure with rollback done. May retry. |
"Saque iniciado mas confirmação interrompida. Consulte /v1/transactions/<id>" | Operation completed, response interrupted. Do not retry. Query the transactionId. |
202 Accepted — indeterminate withdrawal
{
"error": "Saque em verificação. Saldo debitado; status final em até 24h.",
"transactionId": "...",
"status": "failed_unknown"
}INFI does not know whether the provider concluded or not. Do not resend. Wait for automatic reconciliation (up to 24h) or query. See Status / failed_unknown.
Retry strategy
| Scenario | Retry? |
|---|---|
Network timeout / 502 on POST /v1/pix | Yes, with externalRef to guarantee idempotency. |
502 on POST /v1/withdraw with message “valor não foi debitado” | Yes. |
502 on POST /v1/withdraw with message “confirmação interrompida” | No. Query /v1/transactions/:id. |
202 failed_unknown | No. Wait. |
429 | Yes, after waiting (suggestion: 1h or exponential backoff with jitter). |
400, 401, 403, 422 | No — fix the cause first. |
For safe retries without duplicating charges, always send externalRef. See Idempotency.