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

# Erros

> Envelope e códigos estáveis

Toda resposta de erro segue o mesmo envelope:

```json theme={null}
{ "error": { "code": "INSUFFICIENT_FUNDS", "message": "saldo insuficiente", "details": { "available_cents": 6555 } } }
```

O campo `code` é **estável** (use-o no seu código; a `message` pode mudar).

| Código                  | HTTP | Quando                                                   |
| ----------------------- | ---- | -------------------------------------------------------- |
| `VALIDATION_ERROR`      | 400  | payload inválido (campos faltando/errados)               |
| `UNAUTHORIZED`          | 401  | chave ausente ou inválida                                |
| `KEY_REVOKED`           | 401  | chave de API revogada                                    |
| `FORBIDDEN`             | 403  | sem permissão para a ação                                |
| `TEST_ONLY`             | 403  | rota de simulação chamada com chave `live`               |
| `ACCOUNT_SUSPENDED`     | 403  | conta suspensa/bloqueada                                 |
| `NOT_FOUND`             | 404  | recurso inexistente (ou fora do seu escopo)              |
| `DUPLICATE_EXTERNAL_ID` | 409  | `external_id` já usado (retorna o recurso em `details`)  |
| `INSUFFICIENT_FUNDS`    | 422  | saldo insuficiente para o saque                          |
| `RATE_BELOW_FLOOR`      | 422  | taxa abaixo do piso permitido                            |
| `INVALID_PIX_KEY`       | 422  | chave PIX inválida                                       |
| `AMOUNT_OUT_OF_RANGE`   | 422  | valor fora dos limites                                   |
| `PROVIDER_ERROR`        | 502  | falha do provedor ao criar a cobrança                    |
| `PROVIDER_TIMEOUT`      | 504  | timeout do provedor — **não** refaça saque sem consultar |

<Warning>
  Em saques, um `504 PROVIDER_TIMEOUT` **não** significa que o saque falhou — o PIX pode ter
  saído. Aguarde o webhook antes de tentar de novo.
</Warning>