# Rate Limiting & Quota

## Rate Limiting

Todas as respostas da API incluem headers de rate limiting que informam o estado atual da sua cota de requisições.

| Header | Tipo | Descrição |
|--------|------|-----------|
| `X-RateLimit-Limit` | integer | Número máximo de requisições permitidas por minuto para o usuário |
| `X-RateLimit-Remaining` | integer | Número de requisições restantes na janela atual |
| `X-RateLimit-Reset` | integer | Unix timestamp (segundos) indicando quando a janela de rate limit será reiniciada |

O rate limit é aplicado **por usuário** (identificado via token JWT) no API Gateway.

## Quota

Além do rate limit por minuto, cada tenant pode possuir uma **quota** que limita o número total de requisições em um período maior (diário, semanal, mensal ou anual). Quando o tenant possui uma política de quota ativa, todas as respostas incluem os seguintes headers:

| Header | Tipo | Descrição |
|--------|------|-----------|
| `X-Quota-Limit` | integer | Limite total de requisições da quota do tenant no período |
| `X-Quota-Used` | integer | Número de requisições já consumidas no período atual |
| `X-Quota-Remaining` | integer | Número de requisições restantes no período atual |
| `X-Quota-Period` | string | Período da quota: `daily`, `weekly`, `monthly`, `yearly` ou `custom` |
| `X-Quota-Reset` | integer | Unix timestamp (segundos) indicando quando a quota será reiniciada |

Quando a quota é excedida, a API retorna HTTP `429`.

Quotas podem ser configuradas **por endpoint** ou **globalmente** para o tenant. Consulte seu contrato ou entre em contato com o suporte para detalhes sobre sua quota.

## Resposta 429 — Too Many Requests

Quando o rate limit ou a quota são excedidos, a API retorna HTTP `429` com uma mensagem em texto plano indicando o motivo:

- **Rate limit excedido:** `rate limit exceeded`
- **Quota excedida:** `limit exceeded: 1000 requests used, limit is 1000`

> **Dica:** Monitore o header `X-Quota-Remaining` nas respostas para evitar o 429 proativamente — quando o valor estiver baixo, reduza a taxa de requisições.

## Estratégia de Retry

Ao receber um `429`, o cliente deve:

1. Ler o header `X-RateLimit-Reset` ou `X-Quota-Reset` para saber quando a janela será reiniciada.
2. Aguardar até o timestamp indicado antes de reenviar a requisição.
3. Caso nenhum header de reset esteja disponível, usar **backoff exponencial com jitter**.

**Exemplo em Python:**

```python
import time, random, httpx

def request_com_retry(client, method, url, **kwargs):
    for tentativa in range(5):
        resp = client.request(method, url, **kwargs)
        if resp.status_code != 429:
            return resp
        reset = (
            resp.headers.get("X-RateLimit-Reset")
            or resp.headers.get("X-Quota-Reset")
        )
        if reset:
            wait = max(0, int(reset) - int(time.time())) + 1
        else:
            wait = (2 ** tentativa) + random.uniform(0, 1)
        time.sleep(wait)
    return resp
```

---

- Índice geral: https://prismadata.io/llms.txt
- Documentação Redoc interativa: https://prismadata.io/redoc.html