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

# Erros

> Referência completa de códigos de erro da API da VisePag

## Formato de Erro

Todos os erros seguem o mesmo formato JSON:

```json theme={null}
{
  "error": {
    "code": "error_code",
    "message": "Descrição legível do erro"
  }
}
```

***

## Erros de Autenticação

| Status | Código | Descrição |
| - | - | - |
| `401` | `missing_authorization` | Header `Authorization` ausente |
| `401` | `invalid_authorization` | Header inválido; use `Authorization: Bearer YOUR_API_KEY` |
| `401` | `invalid_api_key` | Chave não encontrada |
| `403` | `api_key_revoked` | Chave revogada no dashboard |
| `403` | `account_not_fully_verified` | Conta sem cadastro completo ou sem KYC aprovado |
| `429` | `rate_limit_exceeded` | Limite de requisições excedido |

***

## Erros de Cobranças

| Status | Código | Descrição |
| - | - | - |
| `400` | `invalid_amount` | `amount` deve ser inteiro positivo em centavos |
| `400` | `description_required` | `description` é obrigatória |
| `400` | `customer_name_required` | `customerName` é obrigatório |
| `400` | `customer_document_required` | `customerDocument` é obrigatório |
| `400` | `invalid_customer_document` | CPF ou CNPJ inválido |
| `400` | `invalid_customer_email` | E-mail inválido |
| `400` | `invalid_parameter` | Parâmetro de consulta inválido na lista |
| `422` | `amount_below_minimum` | Valor abaixo do mínimo de R\$ 5,00 |
| `404` | `charge_not_found` | Cobrança não encontrada |
| `502` | `provider_rejected` | A adquirente recusou a cobrança |
| `502` | `charge_creation_uncertain` | A adquirente não confirmou a criação |
| `503` | `provider_unavailable` | Adquirente indisponível no momento |

***

## Erros de Saques

| Status | Código | Descrição |
| - | - | - |
| `400` | `invalid_amount` | Valor deve ser positivo |
| `400` | `invalid_pix_key` | `pixKey` ausente ou inválida para o tipo |
| `400` | `invalid_pix_key_type` | `pixType` inválido. Aceitos: `cpf`, `cnpj`, `email`, `phone`, `random` |
| `422` | `amount_below_minimum` | Valor abaixo do mínimo de saque |
| `422` | `insufficient_balance` | Saldo disponível insuficiente |
| `422` | `amount_below_fee` | Taxa maior que o valor solicitado |
| `404` | `payout_not_found` | Saque não encontrado |

***

## Boas Práticas

> [!TIP]
>
> Sempre verifique o campo `error.code` (não `error.message`) para tratar erros programaticamente, pois as mensagens podem mudar.

```javascript theme={null}
const response = await fetch('https://api.visepag.com/v1/payouts', {
  method: 'POST',
  // ...
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'insufficient_balance':
      console.log('Saldo insuficiente para o saque');
      break;
    case 'rate_limit_exceeded':
      // Aguardar e tentar novamente
      break;
    default:
      console.error(error.message);
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.