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

# Erros

> Formato padrão de erro da API ZynPay

Todo erro da API segue o mesmo formato:

```json theme={null}
{
  "error": {
    "code": "ACCOUNT_NOT_VERIFIED",
    "message": "The account must be verified before it can operate",
    "fields": {
      "amountCents": ["must be greater than or equal to 80"]
    },
    "requestId": "req_8f2c1a..."
  }
}
```

<ResponseField name="code" type="string">
  Código estável para tratamento programático — use este campo na sua lógica, não a mensagem.
</ResponseField>

<ResponseField name="message" type="string">
  Descrição legível do erro, em inglês.
</ResponseField>

<ResponseField name="fields" type="object">
  Sempre presente no envelope. Vem vazio (`{}`) na maioria dos erros; só é preenchido, campo por campo, quando o corpo da requisição falha na validação (`422 VALIDATION_ERROR`).
</ResponseField>

<ResponseField name="requestId" type="string">
  Identificador único da requisição. Envie para o suporte ao relatar um problema.
</ResponseField>

## Erros comuns

| HTTP  | Código                     | Causa                                                                                                           |
| ----- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `400` | `IDEMPOTENCY_KEY_REQUIRED` | O cabeçalho `Idempotency-Key` não foi enviado.                                                                  |
| `401` | `INVALID_API_KEY`          | Chave de API ausente, inválida, revogada ou expirada.                                                           |
| `403` | `ACCOUNT_NOT_VERIFIED`     | A conta ainda não foi [verificada](/primeiros-passos/verificacao-de-conta).                                     |
| `403` | `INSUFFICIENT_SCOPE`       | A chave de API usada não tem o escopo necessário para essa chamada (`pix:read`, `pix:write` ou `balance:read`). |
| `404` | `CHARGE_NOT_FOUND`         | Nenhuma cobrança com esse `id` foi encontrada na sua conta.                                                     |
| `409` | `IDEMPOTENCY_KEY_REUSED`   | O cabeçalho `Idempotency-Key` já foi usado com um corpo diferente.                                              |
| `409` | `PAYOUTS_PAUSED`           | Saques estão temporariamente pausados na plataforma.                                                            |
| `422` | `VALIDATION_ERROR`         | O corpo da requisição não passou na validação — confira `fields` para saber qual campo.                         |
| `422` | `FEE_EXCEEDS_AMOUNT`       | A taxa calculada seria maior ou igual ao valor da cobrança.                                                     |
| `422` | `PIX_KEY_REQUIRED`         | Nenhuma chave Pix de saque cadastrada na conta.                                                                 |

<Tip>
  Sempre confira o `requestId` ao investigar um erro — ele identifica a requisição exata nos nossos logs.
</Tip>