Rate Limits ⏱️

Limites de requisições por plano

Visão Geral

A Alauda API implementa rate limits para garantir uso justo e estabilidade do serviço. Os limites variam de acordo com seu plano de assinatura.

Limites por Plano

Plano	Requests / 15min	Requests / Dia	Requests / Mês
Free	10	10	100
Basic	100	200	5.000
ProPOPULAR	500	1.000	20.000
Premium	10.000	Ilimitado	Ilimitado

Headers de Rate Limit

Cada resposta da API inclui headers informativos sobre seu uso atual:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635789600

X-RateLimit-LimitNúmero máximo de requisições permitidas no período atual
X-RateLimit-RemainingRequisições restantes no período atual
X-RateLimit-ResetTimestamp Unix de quando o limite será resetado

Quando o Limite é Atingido

Ao atingir o rate limit, você receberá uma resposta com status 429 Too Many Requests:

json

{
  "success": false,
  "error": "Limite de requisições atingido. Tente novamente mais tarde.",
  "retry_after": 900
}

O campo retry_after indica quantos segundos você deve aguardar antes de tentar novamente.

Boas Práticas

1. Monitore os Headers

Sempre verifique os headers de rate limit nas respostas para saber quantas requisições você tem disponíveis.

javascript

const response = await fetch('https://api.alauda.mz/api/...');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Requisições restantes: ${remaining}`);
console.log(`Reset em: ${new Date(reset * 1000)}`);

2. Implemente Retry com Backoff

Se você receber um erro 429, aguarde antes de tentar novamente:

javascript

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Aguardando ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries atingido');
}

3. Use Cache

Armazene em cache respostas que não mudam frequentemente:

javascript

const cache = new Map();

async function getCachedData(url) {
  if (cache.has(url)) {
    const { data, timestamp } = cache.get(url);
    
    // Cache válido por 1 hora
    if (Date.now() - timestamp < 3600000) {
      return data;
    }
  }
  
  const response = await fetch(url);
  const data = await response.json();
  
  cache.set(url, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

4. Implemente Queue

Para aplicações com alto volume, use uma fila para controlar requisições:

javascript

class RateLimiter {
  constructor(maxRequests, windowMs) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
    this.queue = [];
    this.requests = [];
  }

  async throttle(fn) {
    // Remove requisições antigas
    const now = Date.now();
    this.requests = this.requests.filter(
      time => now - time < this.windowMs
    );

    // Se atingiu o limite, aguarda
    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = this.requests[0];
      const waitTime = this.windowMs - (now - oldestRequest);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }

    this.requests.push(Date.now());
    return fn();
  }
}

// Uso
const limiter = new RateLimiter(10, 15 * 60 * 1000); // 10 req/15min

await limiter.throttle(() => fetch('https://api.alauda.mz/api/...'));

Dicas para Otimização

📦

Batch Requests

Agrupe múltiplas operações em uma única requisição quando possível

🕐

Off-Peak Hours

Se possível, execute operações pesadas fora dos horários de pico

💾

Cache Agressivo

Armazene resultados que não mudam frequentemente (como info de vídeos)

⚡

Upgrade de Plano

Se você atinge limites constantemente, considere fazer upgrade

Monitoramento de Uso

Você pode monitorar seu uso atual através do dashboard ou da API:

bash

curl -X GET https://api.alauda.mz/api/keys/stats/summary \
  -H "Authorization: Bearer seu_token_jwt"

Resposta

json

{
  "success": true,
  "stats": {
    "totalKeys": 1,
    "activeKeys": 1,
    "totalCredits": 19850,
    "totalRequests": 150,
    "successfulRequests": 145,
    "failedRequests": 5
  }
}

💡

Dica Pro

Configure alertas em sua aplicação quando você atingir 80% do seu rate limit. Isso te dá tempo para implementar estratégias de mitigação antes de atingir o limite.

⭐

Plano Pro Recomendado

Para a maioria dos bots WhatsApp, o plano Pro oferece rate limits generosos (500 req/15min) que dificilmente serão atingidos em uso normal.

⚠️

Importante

Burlar ou tentar contornar os rate limits (usando múltiplas keys, etc) pode resultar em suspensão permanente da sua conta.