Rate Limits

Entenda limites de taxa, quotas e como otimizar o uso da API

Rate Limits e Quotas

O RenderHub implementa rate limits para garantir disponibilidade e performance para todos os usuários. Esta página explica como funcionam os limites e como otimizar seu uso.

Visão Geral dos Limites

Cada plano tem limites específicos de quota e rate:

Plano	Requisições/mês	Requisições/min	Tamanho máx. PDF	Suporte
Gratuito	100	5	5 MB	Comunidade
Starter	1.000	20	10 MB	Email
Pro	10.000	60	25 MB	Prioritário
Business	100.000	120	50 MB	Dedicado
Enterprise	Ilimitado	Custom	Custom	SLA 99.9%

Tipos de Limites

1. Rate Limit (Requisições por Minuto)

Controla quantas requisições você pode fazer por minuto.

Exemplo: Plano Starter = 20 req/min

• ✅ 15 requisições em 1 minuto → OK
• ❌ 25 requisições em 1 minuto → 429 Too Many Requests

2. Quota Mensal (Requisições por Mês)

Limite total de requisições por período de faturamento.

Exemplo: Plano Starter = 1.000 req/mês

• Reseta no dia 1º de cada mês
• Ao atingir 1.000, requisições adicionais retornam 403 Quota Exceeded

3. Limites de Tamanho

• Tamanho máximo do PDF: Varia por plano (5MB - 50MB)
• Tamanho máximo da requisição: 10 MB (payload JSON)
• Timeout: 30 segundos por requisição

Cabeçalhos de Resposta

Cada resposta da API inclui cabeçalhos com informações sobre seus limites:

HTTP/1.1 200 OK
X-RateLimit-Limit: 20          # Limite por minuto
X-RateLimit-Remaining: 15      # Requisições restantes
X-RateLimit-Reset: 1640995200  # Timestamp do reset (Unix)
X-Quota-Limit: 1000            # Quota mensal
X-Quota-Remaining: 750         # Quota restante no mês
X-Quota-Reset: 1643673600      # Reset da quota (Unix)

Códigos de Erro

429 - Too Many Requests

Você excedeu o rate limit por minuto.

{
  "error": "rate_limit_exceeded",
  "message": "Você excedeu 20 requisições por minuto",
  "retry_after": 45
}

Solução: Aguarde retry_after segundos antes de tentar novamente.

403 - Quota Exceeded

Você atingiu sua quota mensal.

{
  "error": "quota_exceeded",
  "message": "Quota mensal de 1.000 requisições excedida",
  "quota_reset": "2024-02-01T00:00:00Z"
}

Solução: Faça upgrade do plano ou aguarde o reset mensal.

Estratégias de Otimização

1. Implementar Retry com Backoff Exponencial

async function generatePDFWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await axios.post('/api/v1/render', data);
      return response.data;
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.headers['retry-after'] || (2 ** i);
        console.log(`Rate limited. Aguardando ${retryAfter}s...`);
        await sleep(retryAfter * 1000);
      } else {
        throw error;
      }
    }
  }
  throw new Error('Máximo de tentativas atingido');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

2. Queue de Requisições

Para processamento em lote, use uma fila:

const Queue = require('bull');
const pdfQueue = new Queue('pdf-generation');

// Adicionar trabalhos à fila
pdfQueue.add({ html: '<h1>Invoice #1</h1>' });
pdfQueue.add({ html: '<h1>Invoice #2</h1>' });

// Processar com rate limiting
pdfQueue.process(async (job) => {
  return await generatePDF(job.data);
});

// Limitar a 15 jobs/min (abaixo do limite de 20)
pdfQueue.setMaxListeners(15);

3. Cache de PDFs

Evite regenerar PDFs idênticos:

const cache = new Map();

async function getCachedPDF(data) {
  const key = JSON.stringify(data);

  if (cache.has(key)) {
    console.log('PDF encontrado no cache');
    return cache.get(key);
  }

  const pdf = await generatePDF(data);
  cache.set(key, pdf);
  return pdf;
}

4. Processamento Assíncrono

Para grandes volumes, use webhooks:

// Requisição inicial (não conta para rate limit)
const response = await axios.post('/api/v1/render/async', {
  mode: 'CONVERT',
  input_type: 'html',
  data: htmlContent,
  webhook_url: 'https://myapp.com/webhooks/pdf-ready'
});

// { "job_id": "job_abc123", "status": "QUEUED" }

// Receber callback quando pronto
app.post('/webhooks/pdf-ready', (req, res) => {
  const { job_id, pdf_url } = req.body;
  // Baixar PDF do pdf_url
});

Monitoramento de Uso

Dashboard

Acesse Dashboard → Uso para ver:

• Gráfico de requisições diárias
• Quota atual vs limite
• Taxa de sucesso/erro
• PDFs por tamanho

API de Métricas

GET /api/v1/usage
Authorization: Bearer SUA_CHAVE_API

{
  "period": "2024-01",
  "quota": {
    "limit": 1000,
    "used": 750,
    "remaining": 250
  },
  "rate_limit": {
    "per_minute": 20,
    "current_usage": 5
  },
  "by_day": [
    { "date": "2024-01-15", "requests": 45 },
    { "date": "2024-01-16", "requests": 52 }
  ]
}

Aumentar Limites

Fazer Upgrade

Vá para Planos para fazer upgrade e aumentar limites.

Enterprise Custom

Para necessidades específicas:

• Limites personalizados
• SLA garantido
• Suporte dedicado
• IP allowlist

Entre em contato: enterprise@renderhub.com

Melhores Práticas

✅ Faça

• Monitore cabeçalhos X-RateLimit-*
• Implemente retry com backoff
• Use cache quando possível
• Processe em lote fora de horário de pico

❌ Não Faça

• Fazer polling agressivo
• Ignorar erros 429
• Criar loops infinitos de retry
• Executar carga de teste em produção

Próximos Passos

• Referência da API - Documentação completa da API
• Webhooks - Processamento assíncrono
• Melhores Práticas - Otimizações avançadas