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:
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).
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çalho | Exemplo | Descrição |
|---|---|---|
| X-RateLimit-Limit | 20 | Total máximo de requisições permitidas na janela atual. |
| X-RateLimit-Remaining | 17 | Quantas requisições ainda restam antes do bloqueio temporário. |
| X-RateLimit-Reset | 1730745600000 | Timestamp 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:
{
"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 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.");
}