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

# Rate Limits

> Limites de requisições e headers de controle da API Pública

# Rate Limits

As tools autenticadas documentadas aqui usam o rate limit global da categoria `public_api`: **60 requisições por minuto por API Key** para garantir estabilidade e uso justo.

## Limites atuais

| Limite                 | Valor                       |
| ---------------------- | --------------------------- |
| Requisições por minuto | 60                          |
| Escopo do limite       | Por API Key                 |
| Janela                 | Deslizante (sliding window) |

<Note>
  Rotas públicas complementares, como quests públicas e eventos de email, podem aplicar limites específicos adicionais.
</Note>

## Headers de resposta

Toda resposta inclui headers que indicam o estado do seu limite:

| Header                  | Descrição                                      | Exemplo |
| ----------------------- | ---------------------------------------------- | ------- |
| `X-RateLimit-Limit`     | Limite máximo de requisições na janela         | `60`    |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual          | `45`    |
| `X-RateLimit-Reset`     | Segundos restantes até o reset da janela atual | `27`    |

## Exemplo de resposta com headers

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 27

{ ... }
```

## Resposta quando o limite é excedido

Quando exceder o limite, a API retorna **429 Too Many Requests**:

```json theme={null}
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Você atingiu o limite de requisições. Por favor, aguarde 27 segundos antes de tentar novamente.",
  "retry_after_seconds": 27,
  "retry_after_message": "27 segundos"
}
```

**Headers na resposta 429:**

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 27
Retry-After: 27
```

## Boas práticas

<Tip>
  Monitore os headers `X-RateLimit-Remaining` e `Retry-After` para evitar bloqueios desnecessários.
</Tip>

1. **Implemente retry com backoff exponencial**: ao receber 429, aguarde o tempo indicado no header `Retry-After`
2. **Interprete `X-RateLimit-Reset` como segundos restantes**: o valor atual não é timestamp Unix
3. **Cache respostas**: dados que mudam pouco (produtos, recompensas) podem ser cacheados localmente
4. **Agrupe operações**: em vez de consultar clientes um a um, use a listagem paginada
5. **Preserve idempotência em retries**: nos 3 writes críticos, reutilize a mesma `X-Idempotency-Key`