Guia de integração
Códigos de Erro Referência consolidada de erros da API Zypfy — por endpoint, por HTTP status code, e por código customizado.
Toda resposta de erro segue este shape:
json Copiar
{
"message" : "Descrição humana do erro." ,
"code" : "OPTIONAL_ERROR_CODE"
}
Alguns erros incluem campos extras contextuais:
json Copiar
{
"message" : "Depósito mínimo é R$ 1.00" ,
"min_amount" : 1.00
}
json Copiar
{
"message" : "Limite de PIX IN por transação é R$ 5000.00" ,
"limit" : 5000.00
}
json Copiar
{
"message" : "Saque temporariamente indisponível. Tente novamente em 120 segundos." ,
"code" : "WITHDRAWAL_COOLDOWN" ,
"retry_after_seconds" : 120
}
# HTTP status codes
Status Situação típica 200 OKSucesso (consultas, saque aceito, deposit idempotente). 201 CreatedRecurso criado com sucesso (depósito novo). 400 Bad RequestValidação falhou (campos ausentes, valores inválidos, regras específicas de saque). 401 UnauthorizedToken ausente ou credenciais inválidas. 403 ForbiddenIP não whitelisted, limite excedido, conta banida. 404 Not FoundRecurso não existe (carteira, usuário). 429 Too Many RequestsRate limit (login) ou cooldown de saque. 500 Internal Server ErrorErro interno — retentar.
# Erros de autenticação (/api/auth/login)
messageHTTP Causa Remediação Provide client_id + client_secret OR email + password.400 Body faltando client_id ou client_secret. Verificar payload. Invalid client_id or client_secret.401 Par inválido. Conferir credenciais no portal. Invalid credentials.401 Campos com tipo errado (proteção NoSQL injection). Garantir que client_id e client_secret são strings. API keys (client_id or client_secret) are not configured for this user.403 Conta sem credenciais geradas. Gerar credenciais no portal. Your account is banned.403 Conta suspensa. Contato com suporte. Too many login attempts. Try again in 15 minutes.429 Rate limit: 25 tentativas/15 min por IP. Esperar ou usar cache de token compartilhado.
# Erros de depósito (/api/payments/deposit)
message / codeHTTP Causa Remediação Missing required fields.400 amount, external_id, payer ou userId ausentes.Revisar payload. Invalid amount.400 amount não é número válido ou ≤ 0.Enviar amount numérico positivo. Depósito mínimo é R$ X400 Valor abaixo do mínimo configurado (min_amount na resposta). Enviar valor ≥ mínimo. Limite de PIX IN por transação é R$ X403 Valor acima de pix_in_limit_daily (limit na resposta). Ajustar limite no dashboard ou dividir em múltiplas cobranças. User not found.404 Usuário do token não existe. Credenciais stale — regerar. Default gateway not configured in settings.500 Gateway padrão não configurado. Contato com suporte.
# Boleto e cartão
codeHTTP Causa Remediação INVALID_METHOD400 paymentMethod fora de pix, boleto, card.Corrigir o valor enviado. DEPOSIT_DISABLED403 Depósitos bloqueados nesta conta. Contato com suporte. BOLETO_DISABLED403 Boleto não habilitado nesta conta. Solicitar liberação ao suporte. CARD_DISABLED403 Cartão não habilitado nesta conta. Solicitar liberação ao suporte. BOLETO_ADDRESS_REQUIRED422 Endereço do pagador ausente ou incompleto. Enviar CEP, rua, número, bairro, cidade e UF. Veja Depósitos Boleto . CARD_AMOUNT_TOO_LOW400 Valor abaixo do mínimo do cartão (R$ 5,00). Ajustar o valor. CARD_AMOUNT_TOO_HIGH400 Valor acima do máximo por venda no cartão. Dividir o pedido ou oferecer PIX. CARD_AMOUNT_INVALID400 Valor não aceito no cartão. Ajustar o valor ou oferecer PIX. CARD_TEMPORARILY_UNAVAILABLE503 Cartão fora do ar no momento. Tentar em alguns minutos ou oferecer PIX.
Recusa do cartão não é mais erro da API: o comprador tenta de novo no checkout seguro e a cobrança segue PENDING. Veja Depósitos Cartão .
# México — SPEI (/api/payments/mx/deposit)
codeHTTP Causa Remediação VALIDATION400 amount ou external_id ausente, ou amount não positivo.Revisar payload. amount é em pesos , com decimais. MXN_DISABLED403 Depósito México não habilitado nesta conta. Solicitar liberação ao suporte. DEPOSIT_DISABLED403 Depósitos bloqueados nesta conta. Contato com suporte. PROVIDER_INVALID_RESPONSE502 O provedor não devolveu transaction_id ou CLABE. Repetir com o mesmo external_id (idempotente). PROVIDER_ERROR4xx O provedor recusou a requisição. Ler a message do erro.
Detalhes do fluxo em Depósitos MXN (México) .
# Erros de saque (/api/withdrawals/withdraw)
# Erros genéricos
messageHTTP Causa Missing required fields for withdrawal.400 amount, external_id, pix_key ou key_type ausentes.Invalid key_type. Allowed values: EMAIL, CPF, CNPJ, PHONE, EVP, COPIAECOLA.400 key_type fora da lista.Invalid amount.400 amount não numérico ou ≤ 0.Saque mínimo é R$ X400 Abaixo do mínimo. min_amount na resposta. Valor excede o máximo permitido por transação (R$ X).400 Acima do teto absoluto. Campos não permitidos no payload: fee, total.400 Tentativa de mass-assignment. Nunca envie fee, total, split_total. Unauthorized IP address.403 IP fora da whitelist. Cadastre no portal. Limite de PIX OUT por transação é R$ X403 Acima de pix_out_limit_daily. User not found.404 Usuário não existe.
codeHTTP Quando ocorre Remediação MISSING_RECEIVER_DOCUMENT400 key_type é EMAIL, PHONE ou EVP sem taxId.Incluir taxId com CPF/CNPJ do recebedor. DOCUMENT_MISMATCH400 taxId enviado em COPIAECOLA não coincide com o CPF/CNPJ do beneficiário original.Conferir CPF/CNPJ ou omitir taxId (cai pra prioridade NORM). QR_CODE_EXPIRED400 QR Code passou da janela de 10 min ou EMV é inválido. Solicitar novo QR e retentar. INSUFFICIENT_BALANCE400 amount + fee > saldo disponível.Consultar saldo em /api/accounts/balance antes. WITHDRAWAL_COOLDOWN429 Gateway em cooldown após falha anterior (retry_after_seconds na resposta). Aguardar e retentar.
# Exemplos de payload de erro
json Copiar
{
"message" : "The field taxId (receiver CPF or CNPJ) is required for withdrawals using PHONE, EMAIL or EVP key types." ,
"code" : "MISSING_RECEIVER_DOCUMENT" ,
"withdrawal" : { "transaction_id" : "b2c3d4e5..." , "status" : "FAILED" }
}
json Copiar
{
"message" : "O CPF/CNPJ informado não confere com o CPF/CNPJ do destinatário da cobrança." ,
"code" : "DOCUMENT_MISMATCH" ,
"withdrawal" : { "transaction_id" : "b2c3d4e5..." , "status" : "FAILED" }
}
json Copiar
{
"message" : "O QR Code informado está expirado ou inválido. Gere um novo código e tente novamente." ,
"code" : "QR_CODE_EXPIRED" ,
"withdrawal" : { "transaction_id" : "b2c3d4e5..." , "status" : "FAILED" }
}
json Copiar
{
"message" : "Saldo insuficiente para processar o saque." ,
"code" : "INSUFFICIENT_BALANCE" ,
"withdrawal" : { "transaction_id" : "b2c3d4e5..." , "status" : "FAILED" }
}
# Erros de consulta (/api/transactions/*)
messageHTTP Causa Provide at least one unique parameter: end_to_end, transaction_id, external_id, txid.400 Query param ausente em /deposit. Provide at least one unique parameter: end_to_end, transaction_id, external_id, idempotency_key.400 Query param ausente em /withdraw. Unauthorized.401 Token ausente.
# Erros de saldo (/api/accounts/balance)
messageHTTP Causa Remediação — 401 Token ausente. Fazer login. — 403 Token inválido/expirado. Renovar token. Wallet not found for this user.404 Carteira não provisionada para este usuário. Contato com suporte (conta recém-criada ou em estado inconsistente).
# Conversão MXN → BRL (/api/accounts/mxn/convert)
codeHTTP Causa Remediação INVALID_AMOUNT400 amount ausente ou não positivo.Enviar valor numérico positivo, em MXN. INSUFFICIENT_MXN_BALANCE400 Saldo MXN menor que o solicitado. O campo detail traz available_mxn e requested_mxn. Converter no máximo o disponível. WALLET_NOT_FOUND404 Carteira não encontrada. Contato com suporte. RATE_UNAVAILABLE503 Câmbio MXN→BRL não configurado no momento. Aguardar e repetir; se persistir, contato com suporte.
# Erros 5xx
messageHTTP Causa Remediação Internal server error.500 Erro não-tratado, normalmente transitório (provedor PIX indisponível, banco lento, timeout externo). Implementar retry exponencial (3 tentativas, 1s / 2s / 4s). Se persistir, contato com suporte com transaction_id / external_id. Error retrieving wallet balance.500 Falha interna na consulta de saldo. Retentar. Default gateway not configured in settings.500 Configuração incompleta na conta. Contato com suporte.
# Padrões de retry
Erro Vale retentar? Estratégia 400 (validação) Não — é erro de payload seu.Corrigir e reenviar. 401 / 403 Sim (após renovar token).Tentar novo login 1× e repetir. 404 Não para consulta; sim para operações novas (pode ser inconsistência transitória).Retry único após 1-2s. 429 Sim respeitando retry_after_seconds ou o header RateLimit-Reset.Esperar antes de retentar. 500 Sim , com exponential backoff.3 tentativas: 1s / 2s / 4s.
# Diagnóstico: checklist rápido
401 em endpoints autenticados? → seu token expirou ou está cached incorretamente. Regere.
403 em saque? → IP não está na whitelist. Confira no portal Credenciais → IPs autorizados .
429 em login? → múltiplos workers tentando logar do mesmo IP. Use cache compartilhado (Redis).
INSUFFICIENT_BALANCE? → consulte /api/accounts/balance e compare com amount + fee antes de retentar.
MISSING_RECEIVER_DOCUMENT? → você não enviou taxId num saque EMAIL/PHONE/EVP.
DOCUMENT_MISMATCH? → o CPF/CNPJ do taxId não bate com o beneficiário do QR. Conferir com quem gerou o QR.
Webhook não chega? → veja o guia Webhooks — configure reconciliação por polling em /api/transactions/*.
Ao abrir ticket de erro, inclua:
transaction_id ou external_id da transação.
Timestamp aproximado (com timezone).
Payload enviado (sem credenciais).
Resposta recebida (HTTP status + body).
IP de origem do request.
Assim a equipe consegue localizar o registro no banco e reproduzir o caminho da sua chamada.