Errores
La API Coufai devuelve los errores con un cuerpo simple:
{ "error": "mensagem em português" }El HTTP status es la fuente primaria para clasificar el error programáticamente. No hay campo code estable; basa tu lógica en status + tipo de operación.
Si necesitas soporte para un caso, anota: fecha/hora UTC, endpoint y el cuerpo enviado. El equipo Coufai correlaciona por los logs internos.
Por status
400 Bad Request — payload inválido
Ocurre cuando algún campo falta o tiene el tipo equivocado. Ejemplos:
| Mensaje | 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 |
"customer.document.number não é um CPF válido (dígito verificador incorreto)." | /v1/pix |
"customer.document.number não é um CNPJ válido (dígito verificador incorreto)." | /v1/pix |
"Valor abaixo do mínimo permitido (R$ X,YY)." / "Valor acima do máximo permitido (R$ X,YY)." | /v1/pix (rango de valor de la cuenta) |
"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 — autenticación
| Mensaje |
|---|
"API key obrigatória. Use: Authorization: Bearer <key>" |
"API key inválida ou revogada." |
403 Forbidden — autorización
| Mensaje | Causa |
|---|---|
"Conta não está aprovada para uso da API." | KYC pendiente. |
"Conta suspensa. Contate o suporte." | Cuenta bloqueada. |
"IP de origem não autorizado para esta chave." | IP fuera de la lista permitida. |
"Tipo de chave PIX 'X' não autorizado para esta conta." | Restricción de configuración. |
"Saque com chave CPF só permitido para o CPF do responsável cadastrado." | Titularidad. |
"Saque com chave CNPJ só permitido para o CNPJ cadastrado da empresa." | Titularidad. |
404 Not Found
| Mensaje |
|---|
"Transação não encontrada." |
Las transacciones de otros comerciantes también devuelven
404(no403) — para no filtrar existencia.
422 Unprocessable Entity
| Mensaje | Endpoint |
|---|---|
"Saldo insuficiente para realizar o saque." | /v1/withdraw |
429 Too Many Requests — rate limit
| Mensaje | Endpoint |
|---|---|
"Limite de requisições atingido. Tente em 1 hora." | /v1/pix |
"Limite de saques atingido." | /v1/withdraw |
Ver Rate limits.
502 Bad Gateway
| Mensaje | Significado |
|---|---|
"Erro ao comunicar com gateway. Tente novamente." | Falla transiente del proveedor; puedes reintentar. |
"Erro ao processar saque. O valor não foi debitado." | Falla del proveedor con rollback hecho. Puedes reintentar. |
"Saque iniciado mas confirmação interrompida. Consulte /v1/transactions/<id>" | Operación concluida, respuesta interrumpida. No reintentes. Consulta el transactionId. |
Desde 2026-07, un documento con dígito verificador inválido y montos fuera del rango aceptado devuelven 400 (antes venían enmascarados como 502 genérico). Son errores de payload — corrige antes de reenviar, no reintentes.
202 Accepted — retiro indeterminado
{
"error": "Saque em verificação. Saldo debitado; status final em até 24h.",
"transactionId": "...",
"status": "failed_unknown"
}Coufai no sabe si el proveedor concluyó o no. No reenvíes. Espera la conciliación automática (hasta 24h) o consulta. Ver Estados / failed_unknown.
Estrategia de retry
| Escenario | ¿Reintentar? |
|---|---|
Timeout de red / 502 en POST /v1/pix | Sí, con externalRef para garantizar idempotencia. |
502 en POST /v1/withdraw con mensaje “valor não foi debitado” | Sí. |
502 en POST /v1/withdraw con mensaje “confirmação interrompida” | No. Consulta /v1/transactions/:id. |
202 failed_unknown | No. Espera. |
429 | Sí, tras esperar (sugerencia: 1h o backoff exponencial con jitter). |
400, 401, 403, 422 | No — corrige la causa antes. |
Para reintentos seguros sin duplicar cobros, envía siempre externalRef. Ver Idempotencia.