Rate Limits

Cada API key possui um limite de requisições por minuto para garantir a estabilidade da plataforma.

Limite padrão

• 100 requisições por minuto por API key (configurável na criação da key)
• A contagem é avaliada em janelas de 60 segundos

Headers de rate limit

Toda resposta inclui headers informativos sobre o consumo atual:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718825460

Quando o limite é excedido

Resposta 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de 100 requisições por minuto excedido para esta API key."
  }
}

Headers adicionais:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718825460

Retry-After indica quantos segundos aguardar antes de tentar novamente.

Configuração personalizada

Ao criar uma API key, o administrador pode definir um rateLimitPerMinute diferente (ex: 200, 500). Keys com alto volume podem ter limites maiores — entre em contato com o suporte.

Boas práticas

1. Respeite Retry-After: Quando receber 429, aguarde o tempo indicado antes de tentar novamente.
2. Implemente backoff exponencial: Em caso de múltiplos 429, aumente progressivamente o intervalo entre retentativas.
3. Batch operações: Prefira criar múltiplos registros via batch (quando disponível) em vez de loops individuais.
4. Cache do lado do cliente: Dados que mudam raramente (séries, turmas) podem ser cacheados localmente.
5. Monitore X-RateLimit-Remaining: Ajuste seu ritmo de requisições antes de atingir o limite.

Exemplo de backoff

async function callWithRetry (url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options)
    if (res.status === 429) {
      if (attempt === maxRetries) throw new Error('Rate limit excedido após retentativas')
      const retryAfter = parseInt(res.headers.get('Retry-After') || '60', 10)
      await sleep(retryAfter * 1000)
      continue
    }
    return res
  }
}