ZypfyDocs Acessar painel
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.

Formato geral

Toda resposta de erro segue este shape:

json
{
  "message": "Descrição humana do erro.",
  "code": "OPTIONAL_ERROR_CODE"
}

Alguns erros incluem campos extras contextuais:

json
{
  "message": "Depósito mínimo é R$ 1.00",
  "min_amount": 1.00
}
json
{
  "message": "Limite de PIX IN por transação é R$ 5000.00",
  "limit": 5000.00
}
json
{
  "message": "Saque temporariamente indisponível. Tente novamente em 120 segundos.",
  "code": "WITHDRAWAL_COOLDOWN",
  "retry_after_seconds": 120
}

HTTP status codes

StatusSituaçã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)

messageHTTPCausaRemediação
Provide client_id + client_secret OR email + password.400Body faltando client_id ou client_secret.Verificar payload.
Invalid client_id or client_secret.401Par inválido.Conferir credenciais no portal.
Invalid credentials.401Campos 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.403Conta sem credenciais geradas.Gerar credenciais no portal.
Your account is banned.403Conta suspensa.Contato com suporte.
Too many login attempts. Try again in 15 minutes.429Rate limit: 25 tentativas/15 min por IP.Esperar ou usar cache de token compartilhado.

Erros de depósito (/api/payments/deposit)

message / codeHTTPCausaRemediação
Missing required fields.400amount, external_id, payer ou userId ausentes.Revisar payload.
Invalid amount.400amount não é número válido ou ≤ 0.Enviar amount numérico positivo.
Depósito mínimo é R$ X400Valor abaixo do mínimo configurado (min_amount na resposta).Enviar valor ≥ mínimo.
Limite de PIX IN por transação é R$ X403Valor acima de pix_in_limit_daily (limit na resposta).Ajustar limite no dashboard ou dividir em múltiplas cobranças.
User not found.404Usuário do token não existe.Credenciais stale — regerar.
Default gateway not configured in settings.500Gateway padrão não configurado.Contato com suporte.

Boleto e cartão

codeHTTPCausaRemediação
INVALID_METHOD400paymentMethod fora de pix, boleto, card.Corrigir o valor enviado.
DEPOSIT_DISABLED403Depósitos bloqueados nesta conta.Contato com suporte.
BOLETO_DISABLED403Boleto não habilitado nesta conta.Solicitar liberação ao suporte.
CARD_DISABLED403Cartão não habilitado nesta conta.Solicitar liberação ao suporte.
BOLETO_ADDRESS_REQUIRED422Endereço do pagador ausente ou incompleto.Enviar CEP, rua, número, bairro, cidade e UF. Veja Depósitos Boleto.
CARD_AMOUNT_TOO_LOW400Valor abaixo do mínimo do cartão (R$ 5,00).Ajustar o valor.
CARD_AMOUNT_TOO_HIGH400Valor acima do máximo por venda no cartão.Dividir o pedido ou oferecer PIX.
CARD_AMOUNT_INVALID400Valor não aceito no cartão.Ajustar o valor ou oferecer PIX.
CARD_TEMPORARILY_UNAVAILABLE503Cartã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)

codeHTTPCausaRemediação
VALIDATION400amount ou external_id ausente, ou amount não positivo.Revisar payload. amount é em pesos, com decimais.
MXN_DISABLED403Depósito México não habilitado nesta conta.Solicitar liberação ao suporte.
DEPOSIT_DISABLED403Depósitos bloqueados nesta conta.Contato com suporte.
PROVIDER_INVALID_RESPONSE502O provedor não devolveu transaction_id ou CLABE.Repetir com o mesmo external_id (idempotente).
PROVIDER_ERROR4xxO 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

messageHTTPCausa
Missing required fields for withdrawal.400amount, external_id, pix_key ou key_type ausentes.
Invalid key_type. Allowed values: EMAIL, CPF, CNPJ, PHONE, EVP, COPIAECOLA.400key_type fora da lista.
Invalid amount.400amount não numérico ou ≤ 0.
Saque mínimo é R$ X400Abaixo do mínimo. min_amount na resposta.
Valor excede o máximo permitido por transação (R$ X).400Acima do teto absoluto.
Campos não permitidos no payload: fee, total.400Tentativa de mass-assignment. Nunca envie fee, total, split_total.
Unauthorized IP address.403IP fora da whitelist. Cadastre no portal.
Limite de PIX OUT por transação é R$ X403Acima de pix_out_limit_daily.
User not found.404Usuário não existe.

Erros com code

codeHTTPQuando ocorreRemediação
MISSING_RECEIVER_DOCUMENT400key_type é EMAIL, PHONE ou EVP sem taxId.Incluir taxId com CPF/CNPJ do recebedor.
DOCUMENT_MISMATCH400taxId 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_EXPIRED400QR Code passou da janela de 10 min ou EMV é inválido.Solicitar novo QR e retentar.
INSUFFICIENT_BALANCE400amount + fee > saldo disponível.Consultar saldo em /api/accounts/balance antes.
WITHDRAWAL_COOLDOWN429Gateway em cooldown após falha anterior (retry_after_seconds na resposta).Aguardar e retentar.

Exemplos de payload de erro

json
{
  "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
{
  "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
{
  "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
{
  "message": "Saldo insuficiente para processar o saque.",
  "code": "INSUFFICIENT_BALANCE",
  "withdrawal": { "transaction_id": "b2c3d4e5...", "status": "FAILED" }
}

Erros de consulta (/api/transactions/*)

messageHTTPCausa
Provide at least one unique parameter: end_to_end, transaction_id, external_id, txid.400Query param ausente em /deposit.
Provide at least one unique parameter: end_to_end, transaction_id, external_id, idempotency_key.400Query param ausente em /withdraw.
Unauthorized.401Token ausente.

Erros de saldo (/api/accounts/balance)

messageHTTPCausaRemediação
—401Token ausente.Fazer login.
—403Token inválido/expirado.Renovar token.
Wallet not found for this user.404Carteira 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)

codeHTTPCausaRemediação
INVALID_AMOUNT400amount ausente ou não positivo.Enviar valor numérico positivo, em MXN.
INSUFFICIENT_MXN_BALANCE400Saldo MXN menor que o solicitado.O campo detail traz available_mxn e requested_mxn. Converter no máximo o disponível.
WALLET_NOT_FOUND404Carteira não encontrada.Contato com suporte.
RATE_UNAVAILABLE503Câmbio MXN→BRL não configurado no momento.Aguardar e repetir; se persistir, contato com suporte.

Erros 5xx

messageHTTPCausaRemediação
Internal server error.500Erro 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.500Falha interna na consulta de saldo.Retentar.
Default gateway not configured in settings.500Configuração incompleta na conta.Contato com suporte.

Padrões de retry

ErroVale retentar?Estratégia
400 (validação)Não — é erro de payload seu.Corrigir e reenviar.
401 / 403Sim (após renovar token).Tentar novo login 1× e repetir.
404Não para consulta; sim para operações novas (pode ser inconsistência transitória).Retry único após 1-2s.
429Sim respeitando retry_after_seconds ou o header RateLimit-Reset.Esperar antes de retentar.
500Sim, com exponential backoff.3 tentativas: 1s / 2s / 4s.

Diagnóstico: checklist rápido

Contato com suporte

Ao abrir ticket de erro, inclua:

  1. transaction_id ou external_id da transação.
  2. Timestamp aproximado (com timezone).
  3. Payload enviado (sem credenciais).
  4. Resposta recebida (HTTP status + body).
  5. IP de origem do request.

Assim a equipe consegue localizar o registro no banco e reproduzir o caminho da sua chamada.