Dicionário de Erros

A Legacy padroniza todos os erros em um formato consistente, ocultando detalhes técnicos internos das adquirentes. Isso garante que sua integração possa tratar erros de forma clara e previsível, independente do provedor subjacente.

Formato padrão de erro

Toda requisição que resultar em falha retorna um objeto com a seguinte estrutura:

{
  "error": "NOME_DO_ERRO",
  "message": "Descrição legível do motivo da falha.",
  "statusCode": 400
}

Campo	Tipo	Descrição
`error`	`string`	Código constante e identificável do erro
`message`	`string`	Explicação amigável e detalhada para o desenvolvedor
`statusCode`	`integer`	Código HTTP associado à resposta

Códigos HTTP utilizados

Status	Quando ocorre
`400 Bad Request`	Dados inválidos ou regra de negócio violada
`401 Unauthorized`	Credenciais ausentes ou inválidas
`403 Forbidden`	Acesso negado — KYC não aprovado, empresa bloqueada ou requisição via browser
`404 Not Found`	Recurso não encontrado para o ID informado
`422 Unprocessable Entity`	Dados estruturalmente válidos mas semanticamente inaceitáveis
`500 Internal Server Error`	Erro interno inesperado na plataforma
`502 Bad Gateway`	Falha ou rejeição temporária de uma adquirente parceira

Erros em Payins

Retornados quando a cobrança não pode ser criada ou processada.

Código	Status HTTP	Significado
`INVALID_DATA`	400	Campos inválidos na requisição — telefone, CEP, CPF ou outros dados com formato incorreto
`PAYER_LIMIT_REJECTED`	400	Limite insuficiente no cartão ou bloqueio temporário imposto pela administradora
`REJECTED_BY_RISK`	400	Negado pelo sistema antifraude devido a pontuação de risco elevada do IP, documento ou padrão da transação
`INVALID_CVV`	400	Código de segurança do cartão incorreto
`PROVIDER_ERROR`	502	A adquirente recusou sem expor o motivo específico

Como tratar

INVALID_DATA: Revise os campos enviados e valide CPF, telefone e CEP no seu front-end antes da requisição.
PAYER_LIMIT_REJECTED: Informe o cliente para tentar outro cartão ou aguardar o desbloqueio pela administradora.
REJECTED_BY_RISK: Não exponha ao cliente que foi o antifraude — use uma mensagem genérica de "pagamento não autorizado".
PROVIDER_ERROR: Implemente uma retentativa com backoff exponencial. Se persistir, tente uma adquirente alternativa.

Erros em Payouts

Retornados quando o saque não pode ser criado ou processado.

Código	Status HTTP	Significado
`INVALID_PIX_KEY`	400	Chave PIX inválida ou não encontrada no DICT do Banco Central
`TEMPORARY_UNAVAILABLE`	502	Saldo indisponível na adquirente temporariamente
`BEYOND_LIMITS`	400	Valor excede o limite permitido para esse horário (comum para valores altos após às 20h)
`PROVIDER_REJECTED`	502	A instituição bancária rejeitou a transferência por motivo não documentado no SPB

Como tratar

INVALID_PIX_KEY: Valide o formato da chave antes de enviar (CPF, CNPJ, EMAIL, PHONE ou EVP) e informe ao usuário para verificar a chave digitada.
TEMPORARY_UNAVAILABLE: Tente novamente em 5 a 10 minutos. Se persistir por mais de 1 hora, acione o suporte.
BEYOND_LIMITS: Reduza o valor da transação ou tente novamente no horário comercial.
PROVIDER_REJECTED: Verifique se a chave PIX pertence a uma conta ativa. O saldo será estornado automaticamente via webhook.

📘
Dica para produção
Monitore os webhooks com status FAILED e REFUSED em Payouts — eles indicam que o saldo foi devolvido à sua conta e a transferência precisa ser refeita. Consulte o guia de Webhooks para entender o fluxo completo.