> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flarepayments.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 Flare Payments

## 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"
  }
}
```

Alguns erros incluem campos extras com contexto adicional:

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "available_balance": 50.00
  }
}
```

***

## 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_disabled`      | Chave desativada no dashboard                             |
| `403`  | `api_key_revoked`       | Chave revogada no dashboard                               |
| `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`  | `missing_id`       | ID da cobrança não informado                   |
| `404`  | `charge_not_found` | Cobrança não encontrada                        |

***

## Erros de Saques

| Status | Código                 | Descrição                                                         |
| ------ | ---------------------- | ----------------------------------------------------------------- |
| `400`  | `invalid_amount`       | Valor deve ser positivo                                           |
| `400`  | `missing_pix_key`      | `pix_key` e `pix_key_type` são obrigatórios                       |
| `400`  | `invalid_pix_key_type` | Tipo inválido. Aceitos: `cpf`, `cnpj`, `email`, `phone`, `random` |
| `400`  | `below_minimum`        | Valor abaixo do mínimo de R\$ 30,00                               |
| `400`  | `insufficient_balance` | Saldo insuficiente (retorna `available_balance`)                  |
| `400`  | `fee_exceeds_amount`   | Taxa maior que o valor solicitado                                 |

***

## Boas Práticas

<Tip>
  Sempre verifique o campo `error.code` (não `error.message`) para tratar erros programaticamente, pois as mensagens podem mudar.
</Tip>

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

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

  switch (error.code) {
    case 'insufficient_balance':
      console.log(`Saldo disponível: R$ ${error.available_balance}`);
      break;
    case 'rate_limit_exceeded':
      // Aguardar e tentar novamente
      break;
    default:
      console.error(error.message);
  }
}
```