Skip to main content
Para garantir a estabilidade mútua e clareza, a Legacy oculta e padroniza os possíveis erros catastróficos vindos de adquirentes e parceiros bancários antes de enviá-los de volta à sua aplicação. Toda vez que uma requisição POST de Payin ou Payout não for finalizada como 201 Created, e sofrer rejeição, você receberá um Bad Request (400) ou Bad Gateway (502) com propriedades contendo error como código fixo e message detalhando o ocorrido.

​
Formato Padrão de Rejeição

{
  "error": "NOME_DO_ERRO_CONSTANTE",
  "message": "Tradução amigável e explicativa do erro",
  "statusCode": 400
}

​
🛑 Família: Insucessos em Payins (Cobranças / Recebimentos)

Erros comumente retornados quando o seu cliente tenta realizar um pagamento na sua loja.

INVALID_DATA

Os dados enviados estão incorretos. Ocorre quando a API rejeita algum campo base como telefone ou CEP.

PAYER_LIMIT_REJECTED

Transação recusada por falta de limite. O cliente não possui saldo o suficiente no Cartão de Crédito ou a administradora do banco dele impôs um bloqueio momentâneo.

REJECTED_BY_RISK

Negada pelo sistema de antifraude. Rejeitado devido às pontuações baixas do payerIp, documentação sem lastro, ou indícios massivos de possível Chargeback.

INVALID_CVV

Código de segurança inválido. O cliente enviou os dígitos errados na propriedade card.

PROVIDER_ERROR

Falha no processamento com o parceiro bancário. Genérico. Significa que a bandeira (Visa, Mastercard) recusou e não expôs o motivo para nós.

​
🛑 Família: Insucessos em Payouts (Saques / Liquidações)

Erros mapeados para as tentativas de transferência do seu saldo via PIX.

INVALID_PIX_KEY

Chave PIX inválida ou não encontrada no DICT. O recebedor enviou um CPF/CNPJ ou Email que não existe registrado no Banco Central sob aquele banco.

TEMPORARY_UNAVAILABLE

Saldo indisponível na adquirente temporariamente. Um erro de balanceamento pontual na rede da Legacy (tentar refazer a chamada em 5 a 10 minutos).

BEYOND_LIMITS

O valor excede o limite permitido neste horário. Geralmente acontece pelo Sistema Financeiro Brasileiro bloquear PIX altos (mais de R$1.000) nos horários noturnos (19:00h até 06:00h).

PROVIDER_REJECTED

A instituição bancária rejeitou a transferência. Genérico. Uma anomalia não documentada no SPB impediu a transferência.