# Rate Limits

A API Movvia aplica limites de requisição por credencial para garantir estabilidade do serviço. Os limites variam por persona e por plano contratado.

## Limites por persona

### Parceiros

| Janela | Limite (plano Partner) |
|  --- | --- |
| Por minuto | 1.000 req/min |
| Por hora | 10.000 req/hora |


Limites customizados estão disponíveis para o plano Enterprise. Para negociar, contate [comercial@movvia.com.br](mailto:comercial@movvia.com.br).

### Vision Dados e Estabelecimentos Comerciais

Limites específicos para estas personas: consultar comercial no onboarding.

## Resposta quando o limite é excedido

Quando o limite é ultrapassado, a API retorna `429 Too Many Requests`.


```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEDIDO",
    "message": "Limite de requisições excedido. Tente novamente em 30 segundos."
  }
}
```

O header `Retry-After` indica em quantos segundos você pode tentar novamente.

## Como lidar com 429

Implemente backoff exponencial com jitter nas retentativas:


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

    const retryAfter = Number(res.headers.get('Retry-After') ?? 2 ** i);
    const jitter = Math.random() * 1000;
    await new Promise(r => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error('Limite de tentativas excedido');
}
```

Plano Explorer
No plano Explorer (sandbox), os limites são mais restritivos. Para testes de carga ou validação de volume, solicite um ambiente dedicado via [comercial@movvia.com.br](mailto:comercial@movvia.com.br).