Rate limits

A Hub API aplica rate limiting em duas camadas independentes para proteger o gateway de tráfego abusivo e isolar tenants em endpoints multi-tenant. A primeira camada é um limite global por IP em rotas sensíveis, executado no middleware antes do roteamento. A segunda é um limite por organização em endpoints de webhook, distribuído via Redis quando disponível e com fallback em memória local por pod.

Esta página descreve os limites em vigor, os headers retornados, o comportamento ao exceder a cota e como mitigar 429 Too Many Requests em integrações.

Limites padrão

O middleware global aplica um teto de 10 requisições por IP a cada 5 minutos sobre rotas autenticação e webhooks. O limite é compartilhado entre todos os pods do mesmo processo Node (in-memory), funcionando como primeira linha de defesa contra brute force e flood.

O bucket por IP é identificado pela chave <ip>:<path>, ou seja, cada rota tem contador independente. O IP é extraído da cadeia X-Forwarded-For (primeiro valor) ou X-Real-IP, com fallback para unknown.

Limites por endpoint

Endpoints com rate limit global por IP

As rotas abaixo estão sob o limite de 10 req/5min por IP, aplicado no middleware.ts:

POST /api/v1/auth/login
POST /api/v1/auth/register
POST /api/v1/auth/forgot-password
POST /api/v1/auth/reset-password
POST /api/v1/auth/refresh
ANY  /api/v1/webhooks/*

Esses caminhos são definidos em RATE_LIMITED_PATHS no middleware. Qualquer rota que comece com um desses prefixos é contabilizada.

Endpoints com rate limit por organização

As rotas de webhook aplicam um segundo limite por orgId, em cima do limite por IP:

POST /api/v1/webhooks/{orgId}/followize
POST /api/v1/webhooks/{orgId}/crm/pipefy

O bucket é identificado por webhook:<provider>:<orgId> e usa Redis como backend principal. Se o Redis estiver indisponível, o limiter cai automaticamente para um Map em memória com janela fixa, capa de 10.000 entradas e limpeza periódica das chaves expiradas.

Demais endpoints

Endpoints fora das listas acima não têm rate limit aplicado pela API — proteção fica a cargo das camadas superiores (Ingress, WAF Cloudflare). Recomendamos ainda assim aplicar throttling do lado do cliente para integrações de alto volume.

Headers X-RateLimit-*

Quando uma requisição passa pelo middleware de rate limit global, a resposta inclui um header informando quantas requisições ainda estão disponíveis na janela atual:

HTTP/1.1 200 OK
X-RateLimit-Remaining: 7
Vary: Origin

429 Too Many Requests

Há duas formas de resposta 429, dependendo de qual camada disparou o bloqueio.

Bloqueio pelo limite global por IP

Quando o IP excede 10 requisições em 5 minutos em uma rota sensível, o middleware retorna:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 300

{
  "error": "Too many requests"
}

O header Retry-After: 300 indica que a janela só será reiniciada após 300 segundos. Não há reset progressivo — o contador é fixo dentro da janela.

Bloqueio pelo limite por organização em webhooks

Quando uma organização excede 30 requisições por minuto em um endpoint de webhook, a rota retorna:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "Rate limit exceeded"
}

Não há Retry-After nesse caso. A janela é fixa de 60 segundos a partir da primeira requisição que abriu o bucket. Se o Redis estiver disponível, o TTL é gerenciado por PEXPIRE NX (TTL definido apenas na criação da chave, sem reset em incrementos subsequentes).

Como otimizar

async function callWithBackoff(url: string, init: RequestInit) {
  let delay = 1000;
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((r) => setTimeout(r, retryAfter || delay));
    delay = Math.min(delay * 2, 32000);
  }
  throw new Error("Rate limit persistente");
}