Limites de taxa

A API programática impõe um limite de taxa simples por conta, além da cota de crédito mensal. Esta página aborda o limite, como ele é calculado e como reduzir a frequência de chamadas de forma adequada.

O limite#

Na prática: uma solicitação por segundo, em média, com picos permitidos de até 60 solicitações em qualquer intervalo de 60 segundos.

Quando você ultrapassa o limite, a próxima solicitação retorna:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

O próprio 429 é registrado, o que é normal — ele sai da janela de 60 segundos como qualquer outra solicitação.

Como funciona a janela#

O limitador é uma janela móvel, não um intervalo fixo:

1. A cada solicitação, o servidor contabiliza quantas das suas solicitações foram recebidas nos últimos 60 segundos.
2. Se esse número já for ≥ 60, a solicitação é rejeitada com 429.
3. Caso contrário, o processo continua, é registrado e contribui para janelas futuras.

Portanto, uma sequência de 60 solicitações em t=0 acaba às t=60, e não no início do minuto seguinte. Não há Retry-After cabeçalho — aguarde cerca de 1 segundo e tente novamente, ou tente novamente mais tarde, conforme descrito abaixo.

Estratégia de recuo#

Um ciclo pragmático:

async function withRetry(fn, { maxAttempts = 6, baseMs = 1000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const isRateLimited =
        /Rate limit exceeded/.test(err.message);
      const isUpstream5xx =
        /Upstream error/.test(err.message);

      if (!isRateLimited && !isUpstream5xx) throw err;
      if (attempt >= maxAttempts) throw err;

      const delay = baseMs * Math.pow(2, attempt - 1) + Math.random() * 250;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Notas:

• Use o backoff exponencial com jitter. Um apartamento setTimeout(1000) a cada nova tentativa, haverá uma colisão interna se você estiver trabalhando em paralelo.
• Não tente novamente 403, 404, 401, ou o esgotamento do crédito 429. Isso não vai se recuperar em um minuto.
• Tentativas de bloqueio. Seis tentativas com baseMs=1000 isso já cobre cerca de 1 minuto de intervalo — se você ainda estiver sujeito a limitação de taxa depois disso, significa que está mantendo uma taxa superior a 60 por minuto e precisa de menos trabalhadores simultâneos, não de mais tentativas.

Projetando dentro dos limites#

O limite é por usuário, não por IP ou por chave — a geração de várias chaves não aumenta esse limite.

Limite de solicitações vs. créditos#

Na prática, cargas de trabalho contínuas esgotam a cota de crédito muito antes de atingirem o limite de taxa. O limite de taxa existe principalmente para impedir que os loops fiquem fora de controle.

Determinando a causa do erro 429#

Tanto o limite de taxa por minuto quanto o limite de crédito mensal retornam um 429 código de status. É possível diferenciá-los verificando o corpo da resposta:

if (res.status === 429) {
  const body = await res.json();
  if (body && body.credits) {
    // Monthly credit limit reached.
    // Do not retry until next month or you upgrade your plan.
  } else {
    // Per-minute rate limit reached.
    // Implement a backoff strategy and retry.
  }
}

Consulte a seção “Erros” para ver a tabela completa de códigos de status.

Erros comuns#

• Noites sem dormir. A para sem loop aguardar O intervalo entre as solicitações consumirá 60 chamadas em milissegundos e causará uma paralisação.
• Paralelização sem um limitador compartilhado. Dois trabalhadores, cada um processando 40 por minuto, atingirão o limite, mesmo que cada um pareça estar “dentro do limite”.
• Tentando novamente 403 / 404 como se fossem limites de taxa. Isso significa "acesso negado" ou "caminho incorreto"; elas não serão bem-sucedidas sem alterar a solicitação ou a conta.
• Pesquisa /créditos para detectar o fator limitante da velocidade. Essa chamada de endpoint conta para o limite de taxa (e consome um crédito). Veja o número real 429 em vez disso.