Quantika API Docs
v1.0 (Public API)

Rate Limits & Cotas

Para garantir a máxima disponibilidade, estabilidade e equidade entre todas as organizações, a API pública do Quantika Hub implementa controle de taxa inteligente em tempo real.

Limites Operacionais

As cotas são calculadas por organização através de algoritmos de janela deslizante (Sliding Window) com Upstash Redis:

Por Token de API
20 req / 10s

Permite rajadas rápidas de até 20 requisições simultâneas em uma janela de 10 segundos (média de 2 req/segundo contínuos).

Anti-Brute Force (Por IP)
Camada Perimetral

Bloqueia chamadas de IPs que disparam credenciais incorretas repetidas vezes antes mesmo de tocar no banco de dados.

Cabeçalhos de Inspeção de Cota

Todas as respostas da API incluem cabeçalhos HTTP para você monitorar o consumo da sua cota em tempo real:

CabeçalhoExemploDescrição
X-RateLimit-Limit20Total máximo de requisições permitidas na janela atual.
X-RateLimit-Remaining17Quantas requisições ainda restam antes do bloqueio temporário.
X-RateLimit-Reset1730745600000Timestamp Unix em milissegundos quando a cota será restaurada.

Como Tratar o Erro 429 (Too Many Requests)

Se a sua aplicação ultrapassar o limite, a API retornará o status HTTP 429 Too Many Requests com o seguinte corpo:

Resposta 429
{
  "error": "Rate limit exceeded. Too many requests."
}

Em scripts de integração em lote (como importação de leads ou disparo de mensagens), recomendamos implementar repetição com espera (Backoff):

Exemplo de Retry com Backoff
// Exemplo de tratamento resiliente com Exponential Backoff
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      // Lê o tempo de reset ou espera proporcional à tentativa
      const resetTime = response.headers.get("X-RateLimit-Reset");
      const delayMs = resetTime 
        ? Math.max(1000, Number(resetTime) - Date.now()) 
        : attempt * 2000;

      console.warn(`Rate limit atingido (429). Aguardando ${delayMs}ms...`);
      await new Promise(resolve => setTimeout(resolve, delayMs));
      continue;
    }

    return response;
  }
  throw new Error("Limite de tentativas excedido.");
}