# Limites de uso

A API de integração aplica um limite de requisições por token, para proteger a plataforma contra loops e abuso. O limite é generoso: o uso normal de um ERP, hub ou automação não encosta nele.

---

## O limite

| Chamadas | Limite | Janela | Conta por |
|---|---|---|---|
| Rotas autenticadas pelo token de integração | 300 | 1 minuto | token (`sk_live_*`) |
| `POST /api/integration/auth` (emitir token) | 5 | 1 minuto | ver [Autenticação](/guia/autenticacao) |

O limite de 300/min vale para **todas as rotas** que você chama com o bearer token de integração (produtos, pedidos, estoque, etc.), somadas. A contagem é **por token**: cada credencial tem seu próprio balde, então separar sistemas em credenciais distintas também separa os limites.

> Emitir o token (`/integration/auth`) tem um limite próprio, mais estrito, porque é a porta de entrada — detalhes em [Autenticação](/guia/autenticacao). Algumas rotas pontuais também podem ter um limite próprio; nesses casos vale o menor.

---

## Headers

Toda resposta de uma rota de integração traz o estado do seu balde:

| Header | Significado |
|---|---|
| `X-RateLimit-Limit` | Teto da janela (ex.: `300`). |
| `X-RateLimit-Remaining` | Quantas chamadas ainda cabem na janela atual. |

Use o `Remaining` para se auto-regular: se estiver baixo, espace as chamadas antes de bater no teto.

---

## Quando você estoura: 429

Passou do teto, a API responde **429 Too Many Requests** com o envelope padrão:

```json
{
  "success": false,
  "code": 429,
  "message_code": "TOO_MANY_REQUESTS",
  "description": "Muitas requisições em pouco tempo. Aguarde antes de tentar novamente."
}
```

Junto vem o header **`Retry-After`**, com os segundos que faltam para a janela reabrir. O tratamento correto:

1. Leia o `Retry-After`.
2. Espere esse tempo — tentar antes não adianta, só renova o bloqueio.
3. Tente a chamada de novo.

---

## Boas práticas

- **Respeite o `Retry-After`.** Reenviar antes do prazo só consome tentativas e mantém você bloqueado.
- **Não faça polling agressivo.** Para acompanhar jobs assíncronos (DANFE, etiquetas), 3–10s entre chamadas basta.
- **Cache o token.** Não chame `/integration/auth` a cada requisição — ele tem o limite mais estrito (5/min). Emita um token e reutilize pelos 30 dias (ver [Autenticação](/guia/autenticacao)).
- **Uma credencial por sistema.** Além de organizar, isola o limite: um sistema em loop não derruba os outros.
- **Trate 429 como sinal de espera, não de falha.** Faça backoff e siga.