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

# Erros

> Entenda o envelope padronizado, request_id e códigos HTTP.

Falhas usam envelope padronizado e incluem `request_id`.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_..."
  }
}
```

Toda resposta carrega o header `X-Request-Id`. Informe esse ID ao suporte para agilizar a investigação.

## Códigos HTTP

| HTTP  | Quando acontece                                               |
| ----- | ------------------------------------------------------------- |
| `401` | Token ausente, inválido ou revogado                           |
| `403` | Conta sem KYC, IP fora da allowlist ou permissão insuficiente |
| `404` | Recurso inexistente ou de outra loja                          |
| `409` | Idempotência divergente                                       |
| `422` | Validação ou pedido recusado                                  |
| `503` | Plataforma/adquirente indisponível                            |

## Erros comuns

| Código                    | HTTP | Causa                                   |
| ------------------------- | ---- | --------------------------------------- |
| `validation_failed`       | 422  | Campo inválido; veja `error.fields`     |
| `amount_below_minimum`    | 422  | Valor abaixo do ticket mínimo do PIX    |
| `amount_above_maximum`    | 422  | Valor acima do ticket máximo do PIX     |
| `payment_not_cancellable` | 422  | Cobrança não está em `waiting_payment`  |
| `idempotency_mismatch`    | 409  | Mesma chave com corpo diferente         |
| `platform_unavailable`    | 503  | Adquirente escolhido não está conectado |

Recurso de outra loja responde `404`, não `403`, inclusive entre lojas do mesmo usuário.