# Rate limits

## Limites padrão

| Janela | Limite (produção) | Limite (sandbox) |
|  --- | --- | --- |
| Por minuto | 1.000 req/min | 100 req/min |
| Por hora | 10.000 req/hora | 1.000 req/hora |


Os limites são por credencial (par `client_id:client_secret`), não por IP.

## Headers de controle

Toda resposta inclui headers de diagnóstico:


```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 743
X-RateLimit-Reset: 1745491200
```

- `X-RateLimit-Limit` — limite da janela atual.
- `X-RateLimit-Remaining` — requisições restantes na janela.
- `X-RateLimit-Reset` — timestamp Unix do reset da janela.


## Resposta 429

Ao atingir o limite, a API retorna `429 Too Many Requests`:


```json
{
  "erro": "RATE_LIMIT_EXCEEDED",
  "mensagem": "Limite de requisições atingido. Tente novamente após o reset.",
  "resetEm": "2026-04-24T10:01:00Z"
}
```

## Tratar 429 no cliente

Implemente retry com backoff exponencial:


```typescript
async function chamarComRetry(
  fn: () => Promise<Response>,
  tentativas = 3
): Promise<Response> {
  for (let i = 0; i < tentativas; i++) {
    const res = await fn();
    if (res.status !== 429) return res;

    const reset = res.headers.get('X-RateLimit-Reset');
    const aguardar = reset
      ? Number(reset) * 1000 - Date.now()
      : Math.pow(2, i) * 1000;

    await new Promise(r => setTimeout(r, Math.max(aguardar, 0)));
  }
  throw new Error('Rate limit excedido após retries');
}
```

## Limites customizados

Para volumes acima dos limites padrão, entre em contato com [comercial@movvia.com.br](mailto:comercial@movvia.com.br). Limites aumentados estão disponíveis no plano Enterprise.

Distribuir requisições
Em batch jobs (importação de placas em massa, reconciliação), distribua as requisições ao longo do tempo em vez de enviar tudo em burst. Use a janela de 1 hora como referência de planejamento.