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

# Erros

> Códigos de erro da Orders API, requestId e exemplos de resposta.

Todas as respostas de erro da Orders API incluem um objeto `error`. Quando aplicável, também incluem `requestId`.

## Formato

```json theme={null}
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid order payload.",
    "details": [],
    "requestId": "01HX..."
  }
}
```

O header `X-Request-Id` também é enviado em erros.

## Códigos

| Código                      | Status | Significado                                 |
| --------------------------- | ------ | ------------------------------------------- |
| `MALFORMED_JSON`            | `400`  | O corpo não é JSON válido.                  |
| `VALIDATION_FAILED`         | `400`  | Payload ou query params inválidos.          |
| `UNAUTHORIZED`              | `401`  | Token ausente ou inválido.                  |
| `TOKEN_REVOKED`             | `403`  | Token revogado.                             |
| `ORDER_NOT_FOUND`           | `404`  | Pedido não existe no dashboard autenticado. |
| `DUPLICATE_EXTERNAL_ID`     | `409`  | Já existe pedido com esse `externalId`.     |
| `INVALID_STATUS_TRANSITION` | `422`  | Mudança de status não permitida.            |
| `RATE_LIMIT_EXCEEDED`       | `429`  | Limite por token atingido.                  |
| `INTERNAL_ERROR`            | `500`  | Erro inesperado.                            |

## Exemplo: pedido não encontrado

```json theme={null}
{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order not found.",
    "requestId": "01HX..."
  }
}
```

Pedidos de outro dashboard também retornam `404 ORDER_NOT_FOUND`, não `403`, para reduzir enumeração.

## Exemplo: rate limit

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "requestId": "01HX..."
  }
}
```

Quando houver `Retry-After`, respeite o tempo antes de reenviar.