Anúncios incomodam? Ir Sem anúncios Hoje 

Limitação de taxa Como parar de receber 429 de todas as APIs que você usa

Publicado em 8 de junho de 2026

HTTP 429 Muitas Solicitações — como ler cabeçalhos Retry-After, implementar retrocesso exponencial com jitter, entender algoritmos de tanque de tokens versus tanque de vazamento e implementar limitação de taxa em sua própria API.

Limitação de taxa: Como parar de receber 429 de todas as APIs que você usa 1

ANUNCIADO Remover?

Você atingiu 429. Seu script está batendo a API há uma hora, seus logs estão cheios de vermelho e a implantação está a apenas 20 minutos. É nesse momento que isso deixa de ser abstrato.

O HTTP 429 Too Many Requests significa que você enviou mais requisições do que o servidor permite em uma janela de tempo específica. Ler a resposta corretamente — e tentar novamente corretamente — é uma habilidade que a maioria dos desenvolvedores só adquire após ter sido queimado. Aqui está a visão completa.

O que o 429 realmente diz

O código de status é apenas metade da mensagem. A informação real está nos cabeçalhos:

Retry-After: 30 — espere 30 segundos antes de tentar novamente. Pode também ser uma data HTTP: Retry-After: Mon, 08 Jun 2026 15:00:00 GMT
X-RateLimit-Limit: 100 — número total de requisições permitidas por janela
X-RateLimit-Remaining: 0 — número de requisições restantes na janela atual (você está em zero)
X-RateLimit-Reset: 1749391200 — marcação Unix quando a janela é reiniciada

Não todas as APIs enviam todos esses dados. O GitHub envia o conjunto completo. O Stripe envia Retry-After. Alguns APIs REST não enviam nada e esperam que você especule. Se você tiver Retry-After, use exatamente esse valor — é o servidor informando o tempo mínimo seguro para esperar. Se você não o fizer, o backoff exponencial será seu recurso de backup.

O jeito errado de tentar novamente

A implementação ingênua parece assim:

async function fetchWithoutBackoff(url) {
  while (true) {
    const res = await fetch(url);
    if (res.ok) return res;
    if (res.status === 429) continue; // immediately retry
  }
}

Isso é ativamente prejudicial. Se 10 instâncias do seu serviço atingirem 429 ao mesmo tempo e todas tentarem novamente imediatamente, cada tentativa ocorre ao mesmo tempo — o problema do rebanho que bate. Você será novamente limitado, imediatamente, em um loop apertado que pode durar indefinidamente e fazer seu cliente parecer que está abusando intencionalmente da API.

Backoff exponencial com jitter

O padrão correto: cada tentativa espera mais tempo do que a anterior (exponencial), e um offset aleatório previne tentativas sincronizadas entre múltiplos clientes (jitter).

async function fetchWithBackoff(url, options = {}, maxRetries = 5) {
  let attempt = 0;

  while (attempt <= maxRetries) {
    const res = await fetch(url, options);

    if (res.ok) return res;

    if (res.status !== 429) {
      throw new Error(`Request failed: ${res.status}`);
    }

    if (attempt === maxRetries) {
      throw new Error(`Rate limited after ${maxRetries} retries`);
    }

    // Use Retry-After if provided; otherwise exponential backoff + jitter
    const retryAfter = res.headers.get('Retry-After');
    let waitMs;

    if (retryAfter) {
      const seconds = isNaN(retryAfter)
        ? (new Date(retryAfter) - Date.now()) / 1000  // HTTP date
        : Number(retryAfter);                          // seconds
      waitMs = seconds * 1000;
    } else {
      const baseDelay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s, 8s, 16s
      const jitter = Math.random() * 1000;            // 0–1000ms random offset
      waitMs = baseDelay + jitter;
    }

    console.log(`Rate limited. Waiting ${Math.round(waitMs / 1000)}s (attempt ${attempt + 1}/${maxRetries})`);
    await new Promise(resolve => setTimeout(resolve, waitMs));
    attempt++;
  }
}

A linha de jitter é a parte que a maioria das implementações ignora. Sem ela, as tentativas de múltiplos processos paralelos ainda chegam em grupos. Com ela, eles se espalham ao longo do intervalo de espera.

Para APIs que retornam Retry-After, use esse valor como o teto — se você ainda estiver recebendo 429 após o tempo especificado de espera, aplique backoff exponencial sobre isso.

Buckets de tokens versus buckets de vazamento

Dois algoritmos dominam as implementações de limitadores de taxa. Entender qual um deles você está lidando revela muito sobre como a API se comportará sob pressão — e qual algoritmo escolher quando estiver construindo o seu próprio.

Bucket de tokens

O bucket contém até N tokens. Cada requisição custa 1 token. Os tokens são repostos a uma taxa fixa (por exemplo, 10 por segundo). Se o bucket estiver vazio, a requisição será rejeitada ou colocada em fila.

Amigável a picos. Se você não fez requisições há algum tempo, acumulou tokens e pode enviar um pico sem atingir o limite. A API do GitHub funciona assim — 5.000 requisições por hora, mas você pode usá-las de uma vez se não tiver usado a API há horas. Ótimo para casos interativos onde o tráfego é espesso.

Bucket de vazamento

As requisições entram em uma fila e são liberadas a uma taxa fixa, independentemente da velocidade com que chegam. Se a fila estiver cheia, as requisições entrantes serão descartadas.

Saída suave, sem picos. Mesmo que você tenha quota disponível, as requisições saem lentamente na taxa configurada. O módulo limit_req do Nginx usa isso. Melhor para proteger sistemas downstream de picos — útil para entrega de webhooks, chamadas para APIs externas e qualquer coisa onde a taxa previsível seja mais importante do que a tolerância a picos.

Qual escolher quando estiver implementando o seu próprio: Pontos de entrada voltados para usuários que precisam de tolerância a picos → bucket de tokens. Entrega de webhooks ou chamadas para APIs externas → bucket de vazamento. Tarefas de fundo onde a taxa suave é importante → bucket de vazamento.

Cálculo de taxas seguras de requisições

Antes de escrever qualquer lógica de tentativa, descubra o que realmente é permitido. Se uma API diz “1.000 requisições por hora”, isso é 16,67 requisições por minuto ou 0,278 requisições por segundo. Adicione um buffer de segurança de 20% e você estará em cerca de 13 requisições por minuto — espaço suficiente para evitar problemas de tempo em casos extremos onde duas janelas se sobrepõem.

Use o Calculadora de Limitação de Taxa para converter números de quota em taxas por segundo e por minuto, encontrar o intervalo correto de espera entre requisições e ver como seu nível de concorrência afeta o risco de picos.

Implementação de limitação de taxa em sua própria API

Se você estiver do outro lado e quiser adicionar um comportamento adequado de 429 à sua própria API:

Escolha a granularidade correta. Por IP é fácil, mas quebra para serviços atrás de NAT ou com egresso compartilhado. Por chave de API é melhor, mas exige autenticação. Por ID do usuário é ideal quando você tiver. Não misture granularidades sem saber qual delas vence.
Sempre retorne Retry-After. Um 429 sem Retry-After obriga cada cliente a implementar seu próprio heurística de backoff. Você terá mais rebanho que bate, não menos.
Use Redis para limitação de taxa distribuída. Contadores em memória não funcionam entre instâncias diferentes de servidor. Redis INCR + EXPIRE é o padrão. Bibliotecas como rate-limiter-flexible (Node) e slowapi (Python/FastAPI) abstraem isso corretamente.
Registre todas as respostas com 429. Um aumento repentino de 429s de uma única chave é ou um bug do cliente ou um uso intencionalmente abusivo. Ambos são importantes para saber em tempo real.
Não limite a taxa em falhas de autenticação. Retorne 401 para credenciais inválidas, não 429. Limitar a taxa em falhas de autenticação é como você acidentalmente bloqueia seus próprios usuários durante uma rotação de credenciais.

O que fazer agora mesmo

Se você está recebendo 429s:

Verifique Retry-After primeiro — use isso se estiver disponível, não invenha seu próprio atraso
Implemente backoff exponencial com jitter — o código acima é pronto para copiar e colar
Registre o cabeçalho X-RateLimit-Remaining em cada resposta — você pode estar consumindo quota mais rápido do que pensa
Cache as respostas onde os dados não mudam com frequência

Se você estiver implementando limitação de taxa: escolha uma biblioteca com suporte a Redis, retorne Retry-After em cada 429, monitore a taxa de 429 por chave e não limite a taxa em falhas de autenticação.

O 429 não é o inimigo — é a API dizendo exatamente o que deu errado e (normalmente) quanto tempo esperar. A maioria dos problemas de limitação de taxa reduz-se a ignorar essa mensagem e tentar novamente imediatamente. Não faça isso.