Rate limits

A API Simplafy Seguros aplica rate limiting com @nestjs/throttler para proteger endpoints contra abuso, evitar custos inesperados em operações destrutivas (INSERT/UPDATE/DELETE) e preservar latência das agregações de KPI. Os limites são contabilizados por IP do cliente, dentro de uma janela deslizante (TTL).

Esta página descreve os limites padrão, o que aparece nos headers da resposta, como reagir ao HTTP 429 e como otimizar o consumo da API.

Limites padrão

O limite global é configurado em src/app.module.ts e vale para todos os endpoints que não declaram override.

Endpoints com limite mais restritivo declaram um override com o decorator @Throttle:

@Throttle({ default: { limit: 10, ttl: 60000 } })
@Get('sdr')
async getKpis(...) { ... }

@Throttle({ default: { limit: 10, ttl: 300000 } }) // 10 requests per 5 minutes
@Post('manual')
async createManualSale(...) { ... }

Headers de rate limit

O ThrottlerGuard do NestJS expõe headers padrão em toda resposta de endpoint protegido pelo guard. Use-os para monitorar o consumo da janela atual sem precisar contabilizar do lado do cliente.

Exemplo de resposta bem-sucedida próxima do limite:

curl -i https://api-seguros.simplafy.com.br/kpi/sdr \
  -H "Authorization: Bearer $TOKEN"

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 37
Content-Type: application/json

429 e backoff

Quando o limite é excedido, a API retorna 429 Too Many Requests. O corpo segue o formato padrão de erros do NestJS:

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

O header Retry-After informa quantos segundos aguardar antes da próxima tentativa. Trate o erro com backoff respeitando esse valor.

Exemplo de retry com backoff em TypeScript:

async function fetchWithRetry(url: string, init: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, init);

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error(`Rate limited after ${maxRetries} retries`);
    }

    const retryAfter = Number(response.headers.get("retry-after") ?? 1);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
}

Como otimizar

Antes de subir os limites de um cliente, revise o padrão de consumo. A maior parte dos 429 vem de loops síncronos ou polling agressivo, não de carga legítima.

Reduza polling

Em vez de fazer polling em /kpi/sdr a cada poucos segundos, prefira janelas mais largas (60 s+) e cache no cliente. Os KPIs são agregações pesadas — chamar com frequência alta não retorna dados mais frescos, apenas consome janela.

Use filtros do servidor

Liste com paginação e filtros (startDate, endDate, agentId) em vez de baixar tudo e filtrar no cliente. Cada requisição economizada conta na janela.

Faça batch quando possível

Para POST /api/sales/manual, agrupe inclusões manuais em batches espaçados em vez de uma chamada por linha. O limite é 10 requisições por 5 minutos, então 60 inclusões enfileiradas levam 30 minutos no fluxo atual.

Inspecione os headers em produção

Adicione observabilidade nos headers X-RateLimit-Remaining e X-RateLimit-Reset. Quando Remaining cai consistentemente para zero antes do Reset, é sinal de que o consumo está mal distribuído na janela.

console.log({
  limit: response.headers.get("x-ratelimit-limit"),
  remaining: response.headers.get("x-ratelimit-remaining"),
  reset: response.headers.get("x-ratelimit-reset"),
});

Próximos passos