Limitação de taxa de API: 4 algoritmos que todo desenvolvedor deve conhecer

Seu trabalho em lote dispara 200 solicitações em 3 segundos e cada resposta retorna 429 Too Many Requests. Seu processador de webhook utiliza uma API de terceiros e fica bloqueado por 15 minutos. Integração de um cliente fica em silêncio porque o loop de novas tentativas esgota a cota diária na primeira hora. Essas falhas compartilham uma causa raiz: o código não respeita os limites de taxa.

Este guia cobre os quatro algoritmos principais de limitação de taxa e mostra como ler X-RateLimit cabeçalhos de qualquer API e fornece código Node.js de copiar e colar para lógica de nova tentativa com espera exponencial.

Os quatro algoritmos de limitação de taxa

Todo limitador de taxa responde à mesma pergunta: “esta solicitação deve ser processada ou devo rejeitá-la?” Os quatro algoritmos diferem na forma como rastreiam o tempo e lidam com rajadas.

1. Janela fixa

A abordagem mais simples. Divida o tempo em intervalos fixos (por exemplo, 1 minuto). Contar solicitações por intervalo. Quando a contagem atingir o limite, rejeite tudo até o início do próximo intervalo.

A janela fixa é fácil de construir: um contador e um carimbo de data/hora por cliente. A desvantagem é a problema de fronteira. Um cliente pode enviar o limite total no final de uma janela e o limite total no início do próximo, obtendo 2x a taxa pretendida em um curto intervalo. API mais antiga do GitHub limitador de taxa utilizado em janelas fixas; desde então, eles mudaram para abordagens mais sofisticadas.

2. Janela deslizante

Em vez de redefinir em limites fixos, a janela desliza a cada solicitação. A qualquer momento, o limitador analisa os últimos N segundos e conta as solicitações nesse período.

A janela deslizante elimina o problema de estouro de limites. O custo é maior memória: você armazena um carimbo de data/hora para cada solicitação, nem um único contador. Redis ZRANGEBYSCORE torna isso prático em escala. A Cloudflare e muitos gateways de API usam janelas deslizantes para limites de taxa por usuário.

3. Balde de tokens

Imagine um balde que contém tokens. Cada solicitação custa um token. Os tokens são recarregados a uma taxa fixa. Se o bucket estiver vazio, a solicitação será rejeitada. Se o balde estiver cheio, os tokens em excesso não serão acumulados.

Token bucket é o algoritmo mais popular em produção. Stripe, AWS API Gateway e a maior parte da nuvem os provedores usam variantes dele. A capacidade do balde controla o tamanho do burst e a taxa de recarga controla rendimento sustentado. Dois parâmetros fornecem controle refinado sobre o formato do tráfego.

4. Balde com vazamento

O inverso do balde de tokens. As solicitações enchem um balde. O balde drena a uma taxa constante. Se o estouros de balde, solicitações em excesso são rejeitadas. A taxa de saída permanece constante independentemente da entrada explosões.

O balde furado funciona bem para modelagem de tráfego onde você precisa de uma taxa de saída constante: trabalhadores em fila, entrega de webhook e pipelines de codificação de vídeo. A desvantagem é que as rajadas ficam na fila em vez do que servido; a latência aumenta sob carga.

Comparando os quatro algoritmos

Algoritmo	Explosão permitida?	Memória	Caso de uso comum
Janela fixa	Explosões de borda (2x no limite)	Baixo (1 contador)	Contadores simples, análises
Janela deslizante	Suave, sem picos de limite	Médio (carimbo de data/hora por solicitação)	Limites de API por usuário
Balde de tokens	Explosões controladas até a capacidade máxima	Baixo (2 valores)	A maioria das APIs de produção (Stripe, AWS)
Balde com vazamento	Na fila, taxa de saída constante	Médio (fila)	Modelagem de tráfego, trabalhadores de fila

Lendo cabeçalhos X-RateLimit

A maioria das APIs inclui informações de limite de taxa nos cabeçalhos de resposta. Três cabeçalhos contam tudo você precisa ficar abaixo do limite:

• X-RateLimit-Limit: máximo de solicitações permitidas por janela
• X-RateLimit-Remaining: solicitações que você deixou na janela atual
• X-RateLimit-Reset: carimbo de data/hora Unix (segundos) quando a janela é reiniciada

Quando você excede o limite, o status da resposta é 429 Too Many Requests e o Retry-After header informa quantos segundos esperar.

Experimente na API do botoi. Este comando curl faz o hash de uma string e imprime os cabeçalhos de limite de taxa:

Cabeçalhos de resposta:

Isso informa que o limite é de 5 solicitações por janela, você tem 4 restantes após esta solicitação e o a janela é redefinida no carimbo de data/hora Unix fornecido. Rastreie esses valores em seu cliente HTTP para evitar atingir 429s em primeiro lugar.

Lógica de nova tentativa com espera exponencial em Node.js

Quando ocorrer um 429, não tente novamente imediatamente. Um ciclo de repetição apertado piora o problema: você fica com taxa limitada por mais tempo e o servidor marcará você como abusivo. Use backoff exponencial com jitter.

Use-o com qualquer endpoint:

A função verifica se há um Retry-After cabeçalho primeiro. Se o servidor lhe disser quanto tempo esperar, respeite. Se não existir nenhum cabeçalho, ele volta para a espera exponencial: 1 segundo, 2 segundos, 4 segundos, 8 segundos. O jitter aleatório (0-500 ms) evita o problema do rebanho estrondoso, onde centenas de os clientes tentam novamente exatamente no mesmo momento.

Limitação proativa: evite erros 429 antes que eles aconteçam

A nova tentativa reativa lida com falhas depois que elas ocorrem. A limitação proativa os impede. Se você sabe o limite de taxa (de documentos ou cabeçalhos), controle suas solicitações no lado do cliente.

Este limitador de taxa do lado do cliente rastreia os carimbos de data/hora da solicitação em uma janela deslizante. Antes de cada solicitação, verifica se a janela está cheia e aguarda, se necessário. Você envia solicitações com segurança máxima taxa sem um único 429.

Modelo de limitação de taxa do Botoi

Botoi usa um sistema de limitação de taxa de dois níveis:

Plano	Explosão (por minuto)	Contingente	Autenticação
Grátis ($0)	5 necessidades/min	100/dia	Nenhum (baseado em IP)
Iniciante (US$ 9/mês)	30 solicitações/min	300.000/mês	Chave de API
Pró (US$ 49/mês)	300 solicitações/min	3.000.000/mês	Chave de API
Negócios (US$ 199/mês)	1.000 solicitações/min	30.000.000/mês	Chave de API

O acesso anônimo rastreia solicitações por endereço IP. A contagem diária é reiniciada à meia-noite UTC por meio de um Contador Cloudflare KV. Solicitações autenticadas usam a chave de API para identificação e limites são aplicadas através Deschave limitador de taxa de token bucket na borda.

Cada resposta de api.botoi.com inclui os três X-RateLimit cabeçalhos descrito acima, portanto, sua lógica de nova tentativa funciona da mesma maneira, independentemente do plano.

Abordagens comprovadas para consumidores de API

• Leia os cabeçalhos de cada resposta. Não codifique limites de taxa na documentação. As APIs alteram os limites sem aviso prévio. Os cabeçalhos são a fonte da verdade.
• Use backoff exponencial com jitter. Intervalos de repetição corrigidos causam sincronização novas tentativas entre clientes. Jitter distribui a carga.
• Lote onde a API oferece suporte. Uma solicitação com 10 itens custa 1 limite de taxa ficha. Dez solicitações individuais custam 10.
• Respostas em cache. Se os dados não mudarem entre as solicitações, armazene o resultado e pule a chamada da API. Registros DNS, certificados SSL e dados WHOIS raramente mudam em minutos.
• Use uma fila para trabalho em segundo plano. Não dispare chamadas de API de um hot loop. Empurrar trabalhe em uma fila (BullMQ, SQS, Cloudflare Queues) e processe itens em uma taxa controlada.
• Monitore sua cota restante. Registro X-RateLimit-Remaining para o seu painel de métricas. Defina um alerta quando cair abaixo de 20% do limite.

Pontos-chave

• Quatro algoritmos dominam. A janela fixa é mais simples. O balde de token é o mais popular. A janela deslizante elimina estouros de limites. Balde com vazamento suaviza a produção.
• Os cabeçalhos X-RateLimit são sua API. Ler Limit, Remaining, e Reset em cada resposta para permanecer sob o limite.
• Backoff exponencial com jitter lida com 429s. Copie o fetchWithRetry função acima em sua base de código e agrupar todas as chamadas de API externas.
• A limitação proativa evita 429s. Acompanhe suas solicitações no lado do cliente em vez de esperar que o servidor recue.
• Nenhuma conta necessária para testar. Acerte qualquer ponto final do botoi em api.botoi.com com 5 solicitações gratuitas por minuto para ver os cabeçalhos de limite de taxa em ação.