> ## Documentation Index
> Fetch the complete documentation index at: https://developers.holdinglegacy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dicionário de Erros

> Entenda os principais códigos de erro padronizados retornados pela API e como lidar com eles.

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

```json theme={null}
{
  "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.

<CardGroup cols={2}>
  <Card title="INVALID_DATA">
    **Os dados enviados estão incorretos.** Ocorre quando a API rejeita algum campo base como telefone ou CEP.
  </Card>

  <Card title="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.
  </Card>

  <Card title="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*.
  </Card>

  <Card title="INVALID_CVV">
    **Código de segurança inválido.** O cliente enviou os dígitos errados na propriedade *card*.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

***

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

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

<CardGroup cols={2}>
  <Card title="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.
  </Card>

  <Card title="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*).
  </Card>

  <Card title="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).
  </Card>

  <Card title="PROVIDER_REJECTED">
    **A instituição bancária rejeitou a transferência.** Genérico. Uma anomalia não documentada no SPB impediu a transferência.
  </Card>
</CardGroup>