Limites e uso

O RuleForge protege a plataforma e o plano do cliente com rate limiting por rota sensível. Esta página documenta os limites, os headers que você recebe e o que fazer quando é bloqueado.

Como o limite funciona

O rate limiter é aplicado por rota sensível e por sujeito autenticado (API key, usuário ou IP para não autenticados). As janelas são dupla: por minuto e por hora.

Rotas monitoradas:

Rota	Chave interna
POST /auth/login	auth.login
POST /auth/register-organization	auth.register
POST /analysis/validate e POST /rulesets/compile	analysis.validate
POST /analysis/logtest-native	analysis.logtest
POST /…/webhooks/{id}/test	webhook.test

Rotas fora dessa lista não têm limite por rota, mas estão sujeitas ao limite global da organização definido pelo plano de cobrança.

Limites padrão

Os valores padrão configurados no servidor:

Janela	Limite padrão	Variável de ambiente
Por minuto	120 requisições	NATIVE_WAZUH_API_RATE_LIMIT_PER_MINUTE
Por hora	5 000 requisições	NATIVE_WAZUH_API_RATE_LIMIT_PER_HOUR

Planos comerciais podem ter limites maiores ou menores — consulte GET /billing/plans/public ou a página Cobrança e planos.

Headers informativos

Toda resposta de uma rota sob rate limit traz, no sucesso:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 2026-04-24T15:31:00Z

• X-RateLimit-Limit: quota configurada para a janela de 1 minuto.
• X-RateLimit-Remaining: quantas chamadas ainda são permitidas antes do reset.
• X-RateLimit-Reset: ISO 8601 UTC — quando o contador reinicia.

Quando é bloqueado

Resposta 429 rate_limited:

{
  "code": "rate_limited",
  "message": "Rate limit excedido.",
  "hint": "Aguarde o reset informado e tente novamente.",
  "details": {
    "route": "analysis.validate",
    "reset_at": "2026-04-24T15:31:00Z"
  },
  "debug_id": "..."
}

Headers adicionais:

Retry-After: 30
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

Retry-After é em segundos e é o único campo que você precisa observar para reagir.

Estratégia recomendada

1. Leia X-RateLimit-Remaining proativamente. Se estiver perto de 0, diminua o ritmo antes de ser bloqueado.
2. Trate 429 explicitamente. Respeite Retry-After; não implemente retry agressivo sem esperar.
3. Use backoff exponencial para erros 5xx, mas não para 429 — nesse caso Retry-After já define o intervalo.
4. Concentre chamadas caras (como analysis/full) em batches. Rodar em paralelo milhares delas é contraproducente.

Exemplo mínimo em Python:

import time, httpx

def call_with_retry(client, method, url, **kwargs):
    for _ in range(5):
        resp = client.request(method, url, **kwargs)
        if resp.status_code != 429:
            return resp
        wait = int(resp.headers.get("Retry-After", "30"))
        time.sleep(wait)
    resp.raise_for_status()

Limites transversais

Além do limite por rota, há limites transversais:

Tamanho do payload

Máximo de 8 MB por requisição (NATIVE_WAZUH_MAX_REQUEST_BYTES=8388608). Quando excedido, a resposta é 413 payload_too_large antes mesmo do body ser lido.

Quota da organização (plano)

Algumas operações (execuções de análise, runs de caso) consomem unidades do plano. Quando o saldo é zerado, o servidor retorna 403 com code específico (plan_quota_exceeded). O consumo atual está em GET /platform/organizations/{id}/billing.

Conexões SSE

Streams (POST /ai/stream, GET /notifications/stream) têm limite de conexões simultâneas por usuário. Quando atingido: 429 com Retry-After.

Login throttle

POST /auth/login é limitado a 5 tentativas em 15 minutos por par (email + IP). POST /auth/register-organization é limitado a 10 tentativas por hora por IP. Excedidos: 429 com Retry-After.

Habilitar/desabilitar (operador)

O operador da instância pode desligar o rate limiting global com NATIVE_WAZUH_API_RATE_LIMIT_ENABLED=false. Apenas para ambientes controlados (teste/CI interno) — em produção deve ficar ativo.

Links relacionados

• Erros — envelope de erros incluindo rate_limited.
• Autenticação
• Cobrança e planos