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

# Erros

> Como ler falhas e o que tentar em seguida.

Quase todos os erros vêm neste envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Produto não encontrado",
    "code": "RESOURCE_NOT_FOUND"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 404
  }
}
```

Trate pelo **`error.code`**, não pelo texto de `message`. O `message` muda por recurso — um 409 de coleção não fala de produto.

## Códigos

| HTTP  | Código                      | Situação                                                                     |
| ----- | --------------------------- | ---------------------------------------------------------------------------- |
| `400` | `VALIDATION_ERROR`          | Body, query ou `X-Store-Id` inválidos                                        |
| `401` | `AUTH_API_KEY_REQUIRED`     | Sem API Key, ou JWT / outro header                                           |
| `401` | `AUTH_API_KEY_INVALID`      | Chave inválida                                                               |
| `401` | `AUTH_API_KEY_EXPIRED`      | Chave vencida                                                                |
| `401` | `AUTH_API_KEY_REVOKED`      | Chave revogada                                                               |
| `403` | `AUTH_SCOPE_DENIED`         | Falta o escopo da operação                                                   |
| `403` | `AUTH_STORE_ACCESS_DENIED`  | Loja não autorizada na chave                                                 |
| `404` | `RESOURCE_NOT_FOUND`        | Recurso inexistente **ou** de outra loja                                     |
| `409` | `DUPLICATE_ENTRY`           | Identificador já existe na loja (slug, código de cupom, método de pagamento) |
| `409` | `INVALID_STATUS_TRANSITION` | Transição de status do pedido não permitida                                  |
| `429` | `RATE_LIMITED`              | Muitas requisições. Espere e tente de novo                                   |

Cada rota da referência lista só os status que ela devolve. `409 DUPLICATE_ENTRY` aparece em criação de produto, coleção, cupom e desconto por pagamento.

Um `404` **não** confirma se o id existe em outra loja. Use o `X-Store-Id` correto.

## Limite de requisições

`429` pode trazer `Retry-After` (segundos). Por minuto:

|           | Leitura (`GET`) | Escrita (`POST` / `PATCH` / `DELETE`) |
| --------- | --------------- | ------------------------------------- |
| Por chave | 120             | 60                                    |

Faça backoff. Não dispare um loop em `429`.

<Info>
  Falhas repetidas de autenticação também são limitadas. Se a chave estiver errada, pause antes de tentar de novo.
</Info>

## Idempotência na criação

No `POST` você pode enviar:

```http theme={null}
Idempotency-Key: pedido-erp-88341
```

Use 1 a 128 caracteres (`A–Z`, `a–z`, `0–9`, `.`, `_`, `-`). O mesmo valor em até 24 horas devolve o **mesmo produto**, com `Idempotent-Replayed: true`.