Rate limit no cliente: token bucket, leaky bucket e limites por host — guia especializado
Sumário do artigo
- Introdução: por que o cliente precisa do próprio rate limit
- Fundamentos: o que é rate limit no cliente e por que o servidor não basta
- Mergulho profundo: famílias de algoritmos e sua matemática
- Método 1: token bucket na prática — implementação sem armadilhas
- Método 2: leaky bucket e gcra — quando é preciso um fluxo uniforme
- Método 3: limites por host — registro, hierarquia e composição
- Método 4: limitador e rotação de ip — como considerar a troca de endereço no modelo
- Erros de projeto comuns no rate limit do cliente
- Ferramentas e recursos para a implementação
- Casos e cenários de aplicação
- Faq: respostas para as perguntas difíceis
- Conclusão: o que fazer a seguir
Introdução: por que o cliente precisa do próprio rate limit
Imagine que você chegou a um banco onde só há um caixa aberto e, atrás de você, formou-se uma fila de mil pessoas. Dá para empurrar, dá para gritar, mas a capacidade de atendimento do caixa não vai aumentar por isso. A única saída é chegar num ritmo razoável ou ser recusado. O rate limit do lado do servidor (limitação de frequência de requisições) é aquele caixa que, num dado momento, simplesmente deixa de te atender. Já o rate limit no cliente é a sua decisão pessoal de não se aproximar do caixa com mais frequência do que ele consegue fisicamente aceitar.
Este artigo é dedicado inteiramente a algoritmos. De propósito, não vamos repetir materiais sobre como tratar o código 429 e montar backoff exponencial, nem vamos discutir quantas threads iniciar. O foco aqui é outro: como, antes mesmo de enviar a requisição, calcular se ela pode ser enviada agora e, caso não possa, quanto tempo esperar. É essa matemática que separa o cliente que “às vezes leva recusa” do cliente que, por anos, trabalha com a mesma API sem irritar seus donos.
O que você vai aprender aqui:
- como funcionam as quatro famílias de algoritmos — fixed window, sliding window, token bucket e leaky bucket — e no que elas diferem em termos de comportamento, não apenas de nome;
- por que token bucket e GCRA (uma variante do leaky bucket) viraram padrão de fato e como implementá-los numa única noite sem erros de arredondamento;
- como montar uma hierarquia de limites: orçamento global, orçamento por host, por endpoint, por chave de autorização e por endereço IP de saída;
- como integrar a rotação de IP ao modelo do limitador sem quebrar nem as cotas do servidor, nem sua própria telemetria;
- quais erros de projeto parecem inofensivos, mas acabam em espera infinita, “explosões” no início do minuto e vazamento de memória.
Vamos falar na linguagem de um engenheiro-mentor: com fórmulas, mas sem esnobismo; com exemplos, mas sem enrolação. Se você escreve um parser, um SDK para uma API de terceiros, uma integração com marketplace ou um agregador que acessa centenas de hosts, vale colocar este guia nos favoritos.
Fundamentos: o que é rate limit no cliente e por que o servidor não basta
Dois olhares sobre o mesmo problema
O rate limit do servidor protege a infraestrutura do dono da API: ele conta suas requisições e responde com recusa quando a cota se esgota. O rate limit no cliente resolve outra tarefa — não chegar à recusa. A diferença é fundamental. O servidor reage a posteriori: a requisição já foi enviada, o canal está ocupado, o log está poluído, a reputação do cliente ficou um pouco arranhada. Já o cliente age de forma antecipada: ele conhece (ou estima) o orçamento e o gasta com cuidado.
Por que não dá para simplesmente depender das recusas do servidor e repetir as tentativas? Porque cada tentativa rejeitada é uma conexão gasta, um token de autorização gasto, uma linha no log de segurança de outra pessoa e, em geral, uma piora da sua posição em sistemas adaptativos de proteção. Um cliente que respeita o ritmo por conta própria parece, aos olhos do servidor, um parceiro bem-educado. Já um cliente que “tenta até deixarem entrar” parece uma fonte de problemas. Adivinhe quem vai ser limitado com mais rigidez na próxima revisão de políticas?
Terminologia básica
- Rate (taxa) — a frequência estável de requisições, por exemplo, “dez requisições por segundo”. É o que o servidor está disposto a aceitar indefinidamente.
- Burst (rajada) — quantas requisições podem ser enviadas de uma vez, em sequência, sem esperar a reposição. O servidor costuma tolerar rajadas curtas se a taxa média não for violada.
- Janela (window) — o intervalo de tempo no qual as requisições são contadas: segundo, minuto, hora, dia.
- Cota (quota) — o número máximo de requisições na janela. A cota dividida pelo comprimento da janela é a taxa média.
- Chave do limite (limit key) — o critério pelo qual o servidor agrupa as requisições: endereço IP, token, conta, par “host mais endpoint”. Um mesmo cliente quase sempre cai simultaneamente sob várias chaves.
- Custo (cost) — o peso de uma requisição. Algumas APIs contam uma busca como dez unidades e a leitura de um card como uma.
Princípio central: o limitador decide “quando”, não “quantos”
É um erro comum confundir o limitador com um semáforo. O semáforo limita o número de operações simultâneas e responde à pergunta “quantas estão em trânsito agora”. O limitador limita a frequência e responde à pergunta “dá para começar mais uma operação agora e, se não der, em quantos milissegundos”. Esses dois mecanismos se complementam, mas não são intercambiáveis. É possível manter uma única conexão e, ainda assim, exceder o limite se as requisições forem curtas. É possível manter cem conexões e respeitar o limite se as requisições forem lentas.
Três propriedades de um bom limitador no cliente
- Previsibilidade. Com a mesma entrada, ele dá a mesma resposta. Nada de “às vezes deixa passar um pouco mais”.
- Baixo custo. A decisão é tomada em tempo constante e com memória constante por chave. Se você tem milhares de hosts, o limitador não pode guardar o histórico de todas as requisições.
- Justiça. Se várias tarefas esperam permissão, elas a recebem na ordem da fila, e não na ordem de “quem acordou na hora certa”.
Guarde esses três critérios: é por eles que vamos comparar os algoritmos na próxima seção.
Mergulho profundo: famílias de algoritmos e sua matemática
Fixed window — um contador honesto, mas traiçoeiro
A variante mais simples: dividimos o tempo em janelas de comprimento fixo, mantemos um contador em cada janela e, ao atingir a cota, esperamos o início da próxima janela. De memória, basta um número e um carimbo de tempo por chave. Parece o ideal.
O problema se chama efeito de borda da janela. Se a cota é de cem requisições por minuto, o cliente pode enviar cem requisições no último segundo de uma janela e mais cem no primeiro segundo da seguinte. Do ponto de vista do cliente, está tudo certo: exatamente cem em cada janela. Do ponto de vista do servidor, chegaram duzentas requisições em dois segundos — o dobro de qualquer interpretação razoável do limite. Se o servidor conta com janela deslizante (e a maioria dos modernos conta assim), você vai levar recusa achando, sinceramente, que é inocente.
O segundo problema é a sincronização das rajadas. Todos os seus workers “acordam” ao mesmo tempo no início do minuto, porque é ali que o contador zera. Isso cria picos de carga na rede, no proxy e no servidor de destino.
Sliding window log — preciso, mas caro
Guardamos os carimbos de tempo de todas as requisições do último intervalo. Antes de enviar, descartamos os que expiraram e contamos os que restaram. O acompanhamento é absolutamente exato, sem efeito de borda. Mas a memória cresce de forma linear com a cota: com cota de dez mil requisições por hora, você guarda dez mil carimbos por chave. Para um host, é tolerável; para mil hosts, não.
Sliding window counter — o meio-termo
Guardamos dois contadores: o da janela atual e o da anterior. A estimativa de carga é o contador atual mais o anterior, multiplicado pela fração da janela anterior que ainda cai no intervalo deslizante. Se já passaram 20 por cento do minuto atual, pegamos 80 por cento do contador anterior. É uma aproximação, mas ela suaviza muito bem a borda e exige apenas duas variáveis. Muitas implementações do lado do servidor usam exatamente isso, então imitá-lo no cliente é uma boa forma de “pensar como o servidor”.
Token bucket — o balde de fichas
Imagine um balde com capacidade para B fichas. A cada segundo, caem nele r fichas, e o excedente transborda. Para enviar uma requisição de custo c, é preciso tirar c fichas. Se não houver fichas suficientes, é preciso esperar que elas caiam.
Dois parâmetros dão duas propriedades independentes. O parâmetro r é a taxa estável: por mais que você espere, o ritmo de longo prazo não vai passar de r requisições por segundo. O parâmetro B é a rajada máxima: depois de um período ocioso, é possível enviar B requisições de uma vez. Isso casa perfeitamente com a forma como as políticas reais de servidor são formuladas: “no máximo cem por minuto, no máximo dez de uma vez”.
O detalhe crucial da implementação é a reposição preguiçosa. Não é preciso uma thread em segundo plano que adiciona fichas a cada segundo. Basta, a cada acesso, calcular quanto tempo passou desde o último acesso e adicionar a quantidade correspondente: tokens = min(B, tokens + elapsed * r). Dois números por chave, cálculo em tempo constante. Atende completamente ao critério de baixo custo.
Leaky bucket — o balde furado
Aqui a metáfora é a inversa: as requisições entram no balde e saem pelo furo no fundo a uma velocidade constante r. Se o balde transbordar, a nova requisição é rejeitada ou fica esperando. A saída é sempre uniforme: nada de rajadas, estritamente uma requisição a cada 1/r segundos. Se o servidor não tolera rajadas ou se você quer um perfil de tráfego o mais suave possível, é essa a escolha.
Existem duas leituras do leaky bucket. A primeira é como fila: as requisições são realmente colocadas em um buffer, e um processo separado as libera por um timer. A segunda é como contador: apenas verificamos se o balde imaginário vai transbordar e, então, deixamos passar ou não. Essa segunda leitura, nas telecomunicações, se chama GCRA (Generic Cell Rate Algorithm) e é matematicamente equivalente ao token bucket com outra parametrização. É uma observação importante: se você já implementou token bucket, você também sabe fazer leaky bucket.
GCRA: um único timestamp em vez de contador
O GCRA guarda um único valor — TAT (theoretical arrival time, tempo teórico de chegada): o momento antes do qual a próxima requisição “ideal” não deveria chegar. Parâmetros: intervalo de emissão T = 1/r e tolerância τ igual a (B − 1) * T. O algoritmo:
- Obtemos o tempo atual now.
- Se TAT for menor que now, consideramos TAT igual a now (o balde está vazio há muito tempo).
- Se TAT − τ for maior que now — a requisição chegou cedo demais; o tempo de espera é TAT − τ − now.
- Caso contrário, liberamos a requisição e avançamos TAT em T.
Um número por chave, nenhum contador de ponto flutuante que vai se desviando aos poucos. Por esse motivo, o GCRA é o algoritmo preferido para limitadores distribuídos: seu estado cabe facilmente em um único campo chave-valor e é atualizado de forma atômica.
Tabela comparativa em palavras
- Fixed window: memória mínima, precisão baixa, rajadas nas bordas; serve apenas como proteção grosseira.
- Sliding log: precisão absoluta, memória linear em relação à cota; adequado para poucas chaves com cotas pequenas.
- Sliding counter: memória de duas variáveis, precisão aproximada; imita bem a lógica do servidor.
- Token bucket: memória de duas variáveis, controle explícito da rajada; padrão para SDKs de cliente.
- Leaky bucket / GCRA: memória de uma variável, saída perfeitamente uniforme; padrão para sistemas distribuídos.
Sobre o relógio: monotonicidade e deriva
Todos os algoritmos dependem do “tempo atual”. Use um relógio monotônico (monotonic clock), não o relógio do sistema. O relógio do sistema pode voltar para trás numa sincronização, e seu limitador vai concluir que passou um número negativo de segundos, zerar a reposição ou, pior, liberar uma rajada gigante. O relógio monotônico garante que nunca anda para trás. A única exceção é o limitador distribuído em um armazenamento compartilhado, em que o tempo é tomado do lado do armazenamento, e não dos clientes, para não depender da diferença de relógio entre as máquinas.
Método 1: token bucket na prática — implementação sem armadilhas
Passo 1. Escolha dos parâmetros
Converta a política do servidor no par (r, B). Se a documentação diz “cem requisições por minuto”, a taxa base é r = 100/60 fichas por segundo. A capacidade B é uma decisão à parte. Uma escolha segura para uma API desconhecida é B igual a cinco a dez por cento da cota da janela, ou seja, cinco a dez fichas com cota de cem. Isso permite processar rapidamente um pequeno lote, mas não cria picos que um servidor com janela deslizante vai interpretar como violação.
Melhor ainda — trabalhe com folga: use 80 a 90 por cento da taxa declarada. Contadores do servidor, latências de rede e arredondamentos dos dois lados inevitavelmente introduzem imprecisão, e a folga a absorve.
Passo 2. Estrutura do estado
Para cada chave, guarde: tokens (número real, a quantidade atual de fichas), last (a marcação monotônica do último recálculo), rate, capacity. Proteja o estado com um mutex ou, em código assíncrono, com uma única tarefa-árbitro pela qual passam todas as requisições de fichas.
Passo 3. O algoritmo acquire(cost)
- Pegamos o lock.
- now = monotonic(); elapsed = now − last; last = now.
- tokens = min(capacity, tokens + elapsed * rate).
- Se tokens ≥ cost: tokens −= cost; soltamos o lock; retornamos “zero de espera”.
- Caso contrário: wait = (cost − tokens) / rate; descontamos as fichas para o negativo: tokens −= cost; soltamos o lock; retornamos wait.
- O chamador dorme wait segundos e então envia a requisição.
Repare no passo cinco. O desconto para o negativo é uma reserva. Ele garante a justiça: a próxima chamada verá um saldo negativo e receberá uma espera ainda maior, ou seja, vai para a fila atrás da anterior. Sem a reserva, surge o erro clássico: dez tarefas veem zero fichas ao mesmo tempo, todas calculam a mesma espera, todas acordam juntas e provocam a rajada que o limitador deveria ter evitado.
Passo 4. Limite da profundidade da reserva
A reserva para o negativo pode ir ao infinito: se as tarefas chegam mais rápido do que as fichas são repostas, a fila de espera cresce e o tempo de espera da última tende a horas. Introduza uma espera máxima (max_delay). Se o wait calculado passar do limite, não faça a reserva e retorne o erro “limitador sobrecarregado”. Deixe o agendador de tarefas decidir o que fazer: adiar, reduzir a prioridade, trocar de host. É justamente o ponto em que o limitador no cliente deixa de ser um freio passivo e vira ferramenta de gestão de carga.
Passo 5. Custo ponderado
Permita que as requisições tenham custos diferentes. Endpoints de busca, seleções em massa e operações de escrita costumam ser “mais caros” para o servidor, e muitas APIs refletem isso nas políticas. Se a documentação não diz nada, defina o peso a partir das suas próprias observações de tempo de resposta: uma requisição que o servidor processa mais devagar faz sentido contar como mais cara. A fórmula da espera não muda — o cost apenas entra nela como multiplicador.
Passo 6. Aquecimento e partida a frio
O valor inicial de tokens é uma decisão à parte. Um balde cheio na partida significa uma rajada imediata de B requisições no momento em que o processo inicia. Isso pode ser indesejável se dezenas de processos iniciam juntos depois de um deploy. Mais seguro é começar do zero ou da metade da capacidade. E, se você sabe que o servidor conta a cota por uma janela que não está alinhada ao seu início, a partida do zero é ainda mais honesta.
Checklist do token bucket
- Usa relógio monotônico.
- A reposição é preguiçosa, pela diferença de tempo, sem timers em segundo plano.
- Reserva para o negativo para uma fila justa.
- Tem max_delay e recusa explícita em caso de sobrecarga.
- A taxa é definida com folga em relação à do servidor.
- A capacidade é limitada a uma fatia razoável da cota da janela.
- Há suporte a cost para requisições ponderadas.
- O estado inicial não gera rajada no deploy.
Método 2: leaky bucket e GCRA — quando é preciso um fluxo uniforme
Quando preferir o leaky bucket
O token bucket permite rajadas. Isso é conveniente, mas há situações em que a rajada em si é prejudicial: o servidor reage de forma agressiva a picos curtos, o canal do proxy tem banda limitada, ou você quer que o padrão de tráfego pareça o de um cliente comum, sem pressa. Em todos esses casos, é preciso uma saída com intervalo entre requisições rigidamente constante. É isso que o leaky bucket faz.
Implementação como fila
A variante clássica: um buffer de capacidade fixa e um único consumidor que, a cada T segundos, retira um elemento e o envia. A vantagem é a simplicidade e a clareza. As desvantagens são a necessidade de uma thread ou tarefa, e o fato de o buffer “congelar” se o consumidor parar. Essa abordagem faz sentido quando você já tem um pipeline explícito: uma fila de tarefas de onde as requisições são retiradas uma a uma.
Implementação como GCRA
Para a maioria dos cenários de cliente, a leitura como contador é mais conveniente. Já descrevemos o algoritmo acima; agora veremos como definir os parâmetros. Se for necessário um intervalo estrito, coloque τ = 0: aí a tolerância é zero e as requisições passam no máximo a cada T. Se quiser permitir uma pequena rajada, aumente τ. Assim, uma só implementação cobre tanto o leaky bucket estrito quanto o token bucket. É por isso que o GCRA é uma boa “engine unificada” para uma biblioteca de limitação.
Procedimento passo a passo do GCRA com reserva
- Ler o TAT da chave; se não existir, considerar TAT = now.
- new_TAT = max(TAT, now) + T * cost.
- allow_at = new_TAT − τ − T * cost; é o momento em que a requisição com esse custo já poderia ter sido enviada sem espera.
- Se allow_at ≤ now: gravar new_TAT e retornar “zero de espera”.
- Caso contrário: wait = allow_at − now; se o wait for maior que max_delay — retornar recusa sem gravar; senão, gravar new_TAT e retornar wait.
Em um armazenamento distribuído, os passos de um a cinco são executados em uma única operação atômica — por exemplo, um script do lado do armazenamento. Isso garante que dois clientes não leiam o mesmo TAT e “dupliquem” a permissão.
Equivalência e escolha pelo perfil de carga
Vale entender: token bucket com parâmetros (r, B) e GCRA com parâmetros (T = 1/r, τ = (B − 1)/r) deixam passar exatamente as mesmas sequências de requisições. A diferença está apenas na representação do estado. Por isso, a pergunta “qual é melhor” é, na verdade, outra: você precisa de rajada? Precisa — ponha B maior que um. Não precisa — ponha B = 1 (τ = 0). O resto é questão de gosto e de conveniência de armazenamento.
Checklist do leaky bucket / GCRA
- Foi decidido se é preciso rajada ou um fluxo estritamente uniforme.
- O estado é um único valor TAT por chave.
- A operação de leitura-verificação-gravação é atômica.
- Há max_delay e recusa explícita.
- Na variante distribuída, o tempo é tomado do lado do armazenamento.
Método 3: limites por host — registro, hierarquia e composição
Por que “um limitador para tudo” não funciona
Se o seu cliente acessa apenas uma API, um balde basta. Mas agregadores, parsers e barramentos de integração acessam dezenas e centenas de hosts, cada um com sua política. Um limite global único ou subutiliza hosts rápidos ou sobrecarrega os lentos. É preciso um registro de limitadores: um mapeamento “chave do limite — estado do balde”, em que a chave é construída a partir das características da requisição.
Chave do limite: do host ao endpoint
A chave mínima é o esquema mais o host mais a porta. Dois domínios do mesmo dono costumam dividir a cota, mas subdomínios podem ser contados separadamente; isso precisa vir da documentação ou ser descoberto por observação. Uma chave mais fina é o host mais o padrão de caminho: por exemplo, o endpoint de busca e o endpoint de card de produto têm cotas diferentes. Mais fino ainda — host mais token de autorização, se o servidor conta a cota por chave de API e você tem várias.
Regra prática: construa a chave a partir dos mesmos critérios que o servidor usa para contar. Se o servidor conta por IP, a chave inclui o seu IP de saída. Se conta por token — o token. Se conta por ambos ao mesmo tempo — você precisa de dois limitadores, e a requisição precisa passar por ambos.
Hierarquia de limites
Um sistema bem projetado organiza os limitadores em níveis:
- Global — o orçamento geral do processo. Protege os seus próprios recursos: sockets, memória, banda do canal.
- Por IP de saída — quantas requisições saem por um endereço específico. Nível essencial quando se trabalha com um pool de endereços.
- Por host — a política do servidor de destino como um todo.
- Por endpoint — cotas separadas para métodos caros.
- Por credencial — cotas por token ou conta.
A requisição precisa obter permissão em todos os níveis. Isso é a composição de limitadores.
Composição sem impasse mútuo
A abordagem ingênua é chamar acquire sequencialmente em cada limitador e somar as esperas. Está errado: o primeiro limitador já descontou uma ficha, e o segundo obriga a esperar dez segundos, durante os quais a ficha do primeiro “expira” do ponto de vista da justiça. Pior ainda: duas tarefas que pegam os limitadores em ordens diferentes podem se atrapalhar indefinidamente.
O procedimento correto:
- Para cada limitador, calcular a espera sem descontar (operação peek).
- Pegar o máximo das esperas — essa é a espera total.
- Se a espera passar de max_delay — recusa.
- Caso contrário, executar o desconto em todos os limitadores, passando a eles um único instante de chegada now + wait, para que cada um reserve o recurso para o mesmo momento.
- Dormir wait e enviar.
Sempre percorra os limitadores na mesma ordem fixa (por exemplo, do global para o mais estreito). Isso elimina impasses quando há acesso concorrente.
Configuração e valores padrão
O registro deve ser capaz de criar um limitador para um host nunca visto. Defina um padrão conservador: taxa baixa, rajada mínima. Para hosts conhecidos — configuração explícita. Uma boa prática é manter a política em forma declarativa: host ou padrão, rate, burst, cost por padrão de caminho, a marca “contar por IP” e “contar por token”. Assim, quando a política do servidor mudar, muda um arquivo, não o código.
Despejo e vazamentos
Um registro com milhares de hosts é candidato a vazamento de memória. Hosts que não são acessados há muito tempo precisam ser removidos. Como o estado do balde, depois de um longo período ocioso, fica “cheio” de qualquer jeito (ou o TAT fica no passado), a remoção não perde informação: no próximo acesso, o limitador é recriado no mesmo estado. Use um cache LRU com tamanho limitado ou uma limpeza periódica das entradas cujo last é mais antigo que algumas janelas.
Checklist dos limites por host
- A chave do limite repete os critérios pelos quais o servidor conta.
- Existem níveis: global, IP, host, endpoint, credenciais.
- A composição é via peek — máximo — desconto unificado.
- Os limitadores são percorridos em ordem fixa.
- Há padrões conservadores para hosts desconhecidos.
- As políticas estão na configuração.
- O registro tem tamanho limitado e remove chaves inativas.
Método 4: limitador e rotação de IP — como considerar a troca de endereço no modelo
Por que a rotação quebra o limitador ingênuo
Se o servidor de destino conta a cota por IP, a troca de endereço altera a chave do limite no lado do servidor. Um cliente ingênuo, que mantém um único contador por host, continua freando depois da troca de IP, embora o servidor já veja um “novo” visitante. O erro oposto é mais perigoso: o cliente zera todos os limites na troca de IP, inclusive os que o servidor conta por token ou conta — e leva recusa por uma cota que não tem nada a ver com IP. Conclusão: a rotação deve afetar apenas o nível “por IP de saída” na hierarquia, e os demais níveis devem seguir a própria vida.
Dois modos de troca de endereço
Na infraestrutura da Proxeon, o IP na porta muda ou por timer, ou por link/API (conforme dados de 22.09.2026). São dois cenários essencialmente diferentes para o limitador. Na troca por timer, o cliente não controla o momento: o endereço muda “de fora”, e o limitador por IP precisa saber disso — por evento, por consulta ao endereço atual ou por cronograma, se o intervalo for conhecido. Na troca por link, o próprio cliente dispara a troca e pode sincronizá-la com o próprio estado: aguardar a conclusão das requisições em trânsito, registrar o momento, criar a nova chave “host mais época do IP”.
Qual é a prevalência de cada modo? Conforme dados de 14.11.2026, a fatia de trocas de IP por timer é de 51,1 %, e o restante fica com link/API. Ou seja, as duas estratégias aparecem mais ou menos na mesma proporção, e um limitador universal precisa suportar ambas.
A época do endereço como parte da chave
Em vez de guardar o próprio IP na chave (que você pode não saber de antemão), use a época — um contador que aumenta a cada troca. A chave do nível “por IP” passa a ser o par “porta mais época”. Quando a época muda, a chave antiga simplesmente deixa de ser usada e, mais tarde, é removida pelo registro, e a nova é criada no estado inicial. Repare: o estado inicial, de novo, precisa ser conservador. O novo endereço é um desconhecido para o servidor, e a primeira coisa que ele vai ver é o seu padrão de tráfego.
Alinhar a janela do limitador com o timer de rotação
Conforme dados de 14.11.2026, o intervalo mediano entre trocas de IP por timer é de 120 s, e 78,1 % dos intervalos de timer são múltiplos exatos de um minuto. Isso é muito conveniente para o projeto. Se você tem cota por host de “N requisições por minuto por IP” e o endereço vive dois minutos, o orçamento de um endereço é exatamente duas janelas de minuto. O limitador por IP pode funcionar como token bucket com taxa N/60 e capacidade calculada para não passar de 2N durante a vida do endereço. O importante é não “recuperar” o que ficou para trás: se no primeiro minuto você enviou pouco, no segundo não pode enviar o dobro, porque o servidor conta por janela de minuto, e não pela sua época.
Pausa durante a troca
A troca de endereço não é instantânea. Conforme dados de 14.11.2026, a duração média da própria troca — do comando até o novo endereço — é de 4,56 s, e 80,8 % das trocas cabem em 5 segundos. O que isso significa para o limitador? Durante a troca, as requisições ou saem pelo endereço antigo, ou não saem de jeito nenhum. A estratégia certa é tratar a troca como um curto intervalo de “drenagem”: antes do comando de troca, o limitador deixa de emitir novas permissões, espera a conclusão das requisições em trânsito, executa a troca e então abre a nova época. Como quatro em cada cinco trocas terminam em até cinco segundos, é razoável definir um timeout de espera pelo novo endereço um pouco acima desse valor e passar ao tratamento de exceção se ele for excedido.
Limite a frequência do próprio comando de troca
Eis um insight frequentemente esquecido: o comando de troca de IP também é uma requisição à API, e também precisa ser limitado. Conforme dados de 14.11.2026, a fatia de registros duplicados de trocas por link (intervalo de no máximo 2 s, mesmo IP) é de 1,2 %. São rastros de situações em que o cliente acionou o link duas vezes seguidas: por corrida entre workers, por repetição em timeout, por falta de um ponto único de decisão. A solução é um balde separado com capacidade um e intervalo estrito (leaky bucket puro com τ = 0) para o comando de rotação, mais deduplicação: se a troca já está em andamento, os demais workers esperam o resultado, em vez de iniciar outra. O mesmo princípio usado para os hosts de destino, só que aplicado à sua própria infraestrutura.
Escala e planejamento do orçamento
Para sentir a escala: conforme dados de 14.11.2026, em um dia foram realizadas 2 196 242 trocas de IP em toda a rede Proxeon, com a participação de 7 924 portas de proxy, e a mediana de IPs únicos por modem por dia é de 95. Para o projetista do limitador, isso significa que uma porta passa, em um dia, por dezenas de épocas de endereço, e o estado “por IP” precisa ser leve e rapidamente removível: guardar o histórico de todas as épocas não faz sentido algum, mas garantir o custo constante de criação de uma nova época é obrigatório.
Protocolos e endereçamento de portas
Um detalhe que simplifica a configuração: na Proxeon, a porta SOCKS5 é igual à porta HTTP mais um (conforme dados de 22.09.2026). Se você usa os dois protocolos para o mesmo canal, o limitador por IP deve contá-los como uma única chave, e não duas: o endereço é o mesmo, logo o orçamento também é. Registre a normalização no registro: a chave é construída pela porta HTTP, e a porta SOCKS5 é reduzida a ela subtraindo um.
Limitador distribuído por IP
Quando várias pessoas ou máquinas acessam pela mesma porta, o balde precisa ser compartilhado. Use um armazenamento com operações atômicas, guarde o TAT (GCRA) sob a chave “porta mais época mais host”, atualize com um script do lado do armazenamento e tome o tempo de lá também. Guarde a época de forma centralizada e troque-a de maneira atômica junto com o comando de rotação — assim todos os processos passam de forma coordenada para a nova chave.
Checklist do limitador com rotação
- A rotação afeta apenas o nível “por IP”; os demais níveis não são zerados.
- Os dois modos são suportados: timer e troca por link/API.
- A chave do nível IP inclui a época do endereço.
- A nova época começa em estado conservador.
- A taxa por IP está alinhada à janela do servidor, e não ao comprimento da época.
- Durante a troca, a emissão de permissões é suspensa.
- O próprio comando de rotação é limitado e deduplicado.
- As portas HTTP e SOCKS5 de um mesmo canal são normalizadas numa só chave.
- Para cenários com vários processos, o estado fica em um armazenamento compartilhado.
Erros de projeto comuns no rate limit do cliente
Erro 1. Sleep em vez de limitador
“Vamos colocar uma pausa de cem milissegundos entre as requisições” é a solução mais comum e a mais frágil. Ela não considera o tempo da própria requisição, não funciona com vários workers, não permite rajadas onde elas são permitidas e não protege contra o surgimento delas onde são proibidas. A pausa não é um limitador, é uma imitação dele.
Erro 2. Contar por janela quando o servidor conta de forma deslizante
O efeito de borda da janela foi analisado acima. Se você não tem certeza de como o servidor conta, presuma o pior — janela deslizante — e use token bucket com capacidade modesta.
Erro 3. Corrida sem reserva
Várias tarefas calculam ao mesmo tempo a mesma espera, dormem e acordam juntas. O resultado é exatamente a rajada que o limitador deveria ter evitado. A cura é a reserva (desconto para o negativo ou avanço do TAT) sob lock.
Erro 4. Fila de espera infinita
Sem max_delay, a fila cresce sem limite, e as tarefas esperam minutos e horas, ocupando memória e conexões. O limitador precisa saber recusar.
Erro 5. Relógio do sistema
Um salto de tempo numa sincronização — e o balde ou transborda, ou “congela”. Só relógio monotônico no cliente; só o tempo do armazenamento na variante distribuída.
Erro 6. Zerar todos os limites na troca de IP
Cotas por token e por conta não dependem do endereço. Ao zerá-las, você viola na hora uma política que não tinha nada a ver com você.
Erro 7. Balde cheio na partida
Dezenas de processos depois do deploy iniciam com baldes cheios e disparam uma rajada ao mesmo tempo. Comece com o balde vazio ou adicione um atraso aleatório na partida.
Erro 8. Registro sem remoção
Cada novo host vira uma entrada para sempre. Depois de semanas de operação, o processo mantém na memória limitadores de hosts que nunca mais serão necessários.
Erro 9. Ignorar o custo da requisição
Se o servidor conta uma busca como dez unidades e você conta como uma, seu limitador deixa passar dez vezes mais do que deveria e depois se surpreende sinceramente com a recusa.
Erro 10. Comando de rotação sem limite
A repetição do comando de troca de endereço por timeout ou por vários workers gera duplicatas e trocas desnecessárias. O comando também é um recurso; dê um balde a ele.
Ferramentas e recursos para a implementação
Bibliotecas prontas por ecossistema
- Go: o pacote golang.org/x/time/rate é a implementação de referência de token bucket, com os métodos Allow, Reserve e Wait. O método Reserve retorna um objeto com o tempo de espera e a possibilidade de cancelamento — exatamente o que se precisa para a composição.
- Python: a biblioteca limits oferece fixed window, sliding window e GCRA com diferentes backends; aiolimiter implementa leaky bucket para asyncio; pyrate-limiter suporta várias janelas ao mesmo tempo.
- Java/Kotlin: Bucket4j — token bucket maduro, com suporte a armazenamentos distribuídos; Resilience4j RateLimiter — variante com ciclos fixos de atualização.
- JavaScript/TypeScript: bottleneck sabe limitar por grupos de chaves e se agrupar via armazenamento compartilhado; p-throttle é uma variante minimalista para casos simples.
- Rust: governor — implementação de GCRA com e sem chaves, adequada para código assíncrono.
- .NET: o namespace embutido System.Threading.RateLimiting, com token bucket, sliding window e limitadores particionados por chaves.
Armazenamentos para estado distribuído
Redis e armazenamentos compatíveis com scripts do lado do servidor são o padrão para o GCRA compartilhado: uma única operação atômica, o tempo é tomado pelo comando do armazenamento e as chaves com TTL são removidas automaticamente. Para cenários dentro de um único cluster de aplicações, também servem mecanismos embutidos como caches distribuídos com operações atômicas.
Ferramentas de observabilidade
Um limitador sem métricas é uma caixa-preta. Exporte: o número de permissões sem espera, a distribuição do tempo de espera, o número de recusas por max_delay, o preenchimento atual dos baldes por chave, a frequência de troca de épocas de endereço. Um histograma de espera por host mostra imediatamente onde a política está rígida demais e onde você está no limite.
Infraestrutura de endereços
Para os cenários com rotação, você vai precisar de um provedor que ofereça os dois modos de troca de endereço — por timer e por link/API — e um endereçamento de portas previsível. Na Proxeon, os dois modos estão disponíveis, e a porta SOCKS5 dista exatamente uma unidade da porta HTTP (conforme dados de 22.09.2026), o que simplifica a normalização das chaves no registro de limitadores.
O que ler
- A descrição do GCRA nas especificações de padrões de telecomunicações — a fonte primária para o leaky bucket como contador.
- A documentação do pacote x/time/rate — uma formulação exemplar da semântica de Reserve e Wait.
- As seções sobre limites na documentação de grandes APIs públicas — nelas aparecem todos os modelos de contagem, e é a melhor forma de aprender a traduzir política em parâmetros do balde.
Casos e cenários de aplicação
Cenário 1. Agregador de preços em centenas de hosts
Tarefa: percorrer regularmente cards de produto em várias plataformas, cada uma com a própria política. Solução: registro de limitadores com chave “host mais padrão de caminho”, padrão conservador para plataformas novas e políticas explícitas para as conhecidas. Composição com limite global por número de sockets. O resultado que esses sistemas buscam: carga uniforme em todos os hosts, sem ociosidade nos rápidos e sem sobrecarga nos lentos; quando a política de uma plataforma muda, corrige-se uma linha de configuração. A principal lição — a passagem de um limite global único para uma hierarquia reduz drasticamente a proporção de requisições enviadas “em vão”.
Cenário 2. SDK para API parceira com cota por token e por IP
Tarefa: uma biblioteca para clientes que têm vários tokens e vários endereços de saída. Solução: dois níveis de limitadores — por token e por endereço — com composição via peek e um único instante de chegada. O agendador escolhe o par “token mais endereço” com a menor espera. Lição — o limitador vira ferramenta de roteamento: em vez de “esperar”, ele indica “para onde enviar sem esperar”.
Cenário 3. Parser em endereços móveis com rotação por timer
Tarefa: percorrer páginas públicas por um pool de portas, com endereços trocando por timer. Solução: limitador por IP com chave “porta mais época”, taxa alinhada à janela de minuto do host de destino. Considerando que, conforme dados de 14.11.2026, o intervalo mediano do timer é de 120 s e 78,1 % dos intervalos são múltiplos de um minuto, o orçamento por época é calculado como um número inteiro de janelas de minuto. Durante a troca — e 80,8 % das trocas cabem em 5 segundos (conforme dados de 14.11.2026) — a emissão de permissões é posta em pausa, com timeout um pouco acima desse limite. Lição — alinhar a janela do limitador ao ritmo da rotação livra você das rajadas de “recuperação” no início da nova época.
Cenário 4. Workers com rotação por link e comandos duplicados
Tarefa: vários workers dividem uma porta, e cada um, quando necessário, dispara a troca de endereço. Sintoma — rastros de comandos repetidos nos logs. Solução: um ponto único de rotação com leaky bucket (τ = 0) e deduplicação: se a troca já está em andamento, os outros esperam a conclusão. Conforme dados de 14.11.2026, a fatia de registros duplicados de trocas por link na rede é de 1,2 %; são exatamente as situações que um ponto único de decisão elimina. Lição — é preciso limitar não apenas as requisições a APIs de terceiros, mas também os comandos à sua própria infraestrutura.
Cenário 5. Uma engine única em GCRA para todos os níveis
Tarefa: simplificar a base de código, onde historicamente conviviam fixed window, pausas com sleep e contadores manuais. Solução: uma única implementação de GCRA com parâmetros (T, τ), aplicada em todos os níveis da hierarquia, com estado em armazenamento compartilhado para chaves distribuídas e em memória para as locais. Lição — uma única fórmula substitui o zoológico de soluções e torna o comportamento do sistema previsível.
FAQ: respostas para as perguntas difíceis
No que o token bucket difere essencialmente do leaky bucket, se eles são equivalentes?
Eles são equivalentes como objetos matemáticos: com a correspondência de parâmetros adequada, deixam passar as mesmas sequências. A diferença está na intuição e em qual parâmetro você controla diretamente. O token bucket pensa em termos de “taxa e rajada”; o leaky bucket, em termos de “intervalo e tolerância”. Para políticas do tipo “N por minuto, no máximo M de uma vez”, o primeiro é mais prático; para “exatamente uma requisição a cada T”, o segundo. O GCRA une as duas intuições em um único estado.
Como escolher a capacidade do balde se o servidor não publica a rajada permitida?
Comece com uma fração pequena da cota da janela — na ordem de cinco a dez por cento — e observe. Se não houver recusas e as esperas forem grandes, aumente com cuidado. Lembre-se de que um servidor com janela deslizante não tolera rajadas maiores que a cota em um subintervalo curto; por isso, a capacidade nunca deve chegar perto da cota inteira.
Preciso de limitador se tenho apenas uma thread?
Sim. Uma única thread com requisições curtas excede a cota com facilidade: se a resposta chega em vinte milissegundos, você envia cinquenta requisições por segundo sem nem perceber. O limitador é necessário independentemente do número de threads; ele resolve uma questão diferente do semáforo.
Como limitar requisições com custos diferentes, se o servidor as conta de formas diferentes?
Passe o cost para o acquire. As fichas são descontadas de forma proporcional, e a espera é calculada pela mesma fórmula. Se o custo for desconhecido, estime pelo tempo de resposta ou pelo tamanho da resposta e refine com o tempo. Melhor superestimar do que subestimar.
O que fazer se uma requisição precisa passar por cinco limitadores e cada um dá uma espera diferente?
Primeiro pergunte a todos a espera sem descontar, pegue o máximo e depois desconte em todos para um único instante de chegada. Percorra sempre os limitadores em uma mesma ordem. Se o máximo exceder o limite, recuse sem descontar; caso contrário, os recursos ficariam reservados “em vão”.
Como o limitador deve reagir a uma troca de IP por timer, se eu não sei o momento exato?
Use um evento ou a consulta ao endereço atual; se o intervalo for conhecido, use um cronograma com folga. Na Proxeon, a troca por timer e a troca por link/API são ambos modos previstos (conforme dados de 22.09.2026); se você precisa de sincronização exata, prefira o modo por link: aí o momento da troca é você quem determina e você abre a nova época no seu registro exatamente quando a troca é confirmada.
Por que não se pode zerar todos os limites depois de uma troca de endereço?
Porque o servidor pode contar a cota por vários critérios ao mesmo tempo. O endereço mudou — a cota por IP recomeça, mas a cota por token, conta ou sessão continua contando. Zerando tudo, você viola as políticas que não dependem do endereço. A rotação deve afetar apenas o nível “por IP” na hierarquia.
O que é melhor para um limitador distribuído — token bucket ou GCRA?
GCRA. Ele tem um único valor de estado, é mais simples de atualizar de forma atômica e mais simples de guardar com TTL. O token bucket exige dois valores e uma lógica de reposição um pouco mais complexa, o que complica o script atômico. Semanticamente, ambos dão o mesmo resultado.
Como verificar se o limitador funciona corretamente antes de ir para produção?
Escreva um teste com relógio substituível: forneça as requisições nos momentos definidos e compare as decisões com a sequência de referência. Verifique os casos de borda: tempo zero, longo período ocioso, chegada simultânea de muitas requisições, custo maior que a capacidade (deve haver recusa explícita, e não espera infinita). Teste à parte a composição: dois limitadores com taxas diferentes e a verificação de que nenhum deles deixa passar mais do que a própria cota.
Conclusão: o que fazer a seguir
O rate limit no cliente não é um freio, é um sistema de gestão. Um limitador bem construído faz três coisas: não chega à recusa, usa o orçamento disponível de forma uniforme e indica ao agendador para onde e quando enviar a próxima requisição. Na base, há uma única fórmula, seja token bucket ou GCRA, mas ela precisa ser cercada de disciplina: relógio monotônico, reserva sob lock, espera máxima, hierarquia de chaves e remoção de entradas.
Resumo breve:
- Fixed window é simples, mas traiçoeira nas bordas; prefira token bucket ou GCRA.
- Token bucket dá controle separado de taxa e rajada; GCRA faz o mesmo em um único número de estado.
- A chave do limite repete os critérios pelos quais o servidor conta; os limitadores se organizam em hierarquia e se compõem via peek — máximo — desconto unificado.
- A rotação de endereço altera apenas o nível “por IP”; o comando de rotação merece um balde próprio.
- As métricas de espera e de recusas são o único modo honesto de saber se a sua política bate com a do servidor.
Próximos passos para você: escolha uma engine única (recomendamos GCRA), descreva as políticas dos hosts conhecidos na configuração, adicione um padrão conservador, ligue as métricas e rode os testes com relógio substituível. Se trabalhar com um pool de endereços, inclua a época na chave e um balde separado para o comando de troca. Depois disso, seu cliente vai parecer, para qualquer servidor, o convidado mais educado — aquele a quem nunca se recusa.