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

# Erros

> Formato padrão de erro e catálogo de códigos.

## Formato

Todos os erros retornam JSON com este formato:

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "Campo 'amountBrl' é obrigatório",
  "details": { "field": "amountBrl" },
  "requestId": "req_01hxy..."
}
```

O header `x-request-id` também está presente em cada resposta. Inclua-o ao abrir um ticket.

## Códigos comuns

| HTTP | `error`            | Significado                                               |
| ---- | ------------------ | --------------------------------------------------------- |
| 400  | `VALIDATION_ERROR` | Input inválido (ver `details`).                           |
| 400  | `QUOTE_EXPIRED`    | Cotação passou do prazo de 30 s.                          |
| 401  | `UNAUTHORIZED`     | Credenciais ausentes ou inválidas.                        |
| 403  | `FORBIDDEN`        | Merchant suspenso ou sem permissão para o recurso.        |
| 404  | `NOT_FOUND`        | Recurso inexistente ou pertencente a outro merchant.      |
| 409  | `CONFLICT`         | Recurso duplicado (ex.: receiver com mesmo documento).    |
| 422  | `LIMIT_EXCEEDED`   | Operação excede o limite do receiver (diário ou noturno). |
| 422  | `KYC_NOT_APPROVED` | Receiver sem KYC aprovado.                                |
| 429  | `RATE_LIMITED`     | Muitas requisições — respeite o header `Retry-After`.     |
| 500  | `INTERNAL_ERROR`   | Erro interno. Veja `requestId` e abra ticket.             |

## Retries

Erros `5xx` e `429` podem ser retentados com backoff exponencial. Erros `4xx` (exceto `429`) NÃO devem ser retentados — o input está incorreto.