Limitação de taxa e proteção contra abuso de API: token bucket, leaky bucket, quotas e backoff

A limitação de taxa é um daqueles controlos que parecem simples num diagrama e ficam cheios de nuances assim que o tráfego real chega: apps móveis a repetir pedidos em redes instáveis, integrações de parceiros que enviam lotes, bots que rodam IPs e tarefas em segundo plano que, sem querer, fazem “stampede” aos endpoints. Em 2026, a maioria das APIs em produção combina várias técnicas — token bucket para tolerar picos, leaky bucket para suavizar o fluxo, quotas para garantir justiça ao longo de janelas maiores e regras de backoff para impedir que as repetições transformem uma degradação parcial numa falha total. Este artigo explica como estas peças se encaixam, do que o protegem e quais as escolhas de desenho que normalmente importam mais do que o nome do algoritmo.

O que a limitação de taxa realmente protege: disponibilidade, custo e justiça

No nível mais básico, a limitação de taxa impede que um único consumidor — malicioso ou simplesmente com um bug — use de forma desproporcionada CPU, ligações à base de dados ou capacidade de serviços a jusante. Não é apenas “demasiados pedidos”; é proteger recursos partilhados e manter a latência previsível para todos os outros. Um único endpoint que aciona fan-out caro (pesquisa, recomendações, consultas a terceiros) pode tornar-se o ponto fraco que empurra todo o serviço para uma espiral de filas.

Também protege custos e limites contratuais. APIs públicas muitas vezes têm um modelo económico por trás: largura de banda, tempo de computação, escalões pagos ou acordos com parceiros. Mesmo APIs internas podem ter restrições quando estão à frente de serviços com cobrança por utilização. A limitação de taxa torna essas restrições aplicáveis e, quando combinada com quotas claras, dá às equipas uma forma de comunicar expectativas em vez de depender de “throttling” silencioso ou promessas vagas de “best effort”.

Por fim, a limitação de taxa é um mecanismo de justiça. Dois clientes podem ser “legítimos” e ainda assim prejudicar-se: um envia tráfego constante, outro envia picos no topo de cada minuto. Sem um limitador que entenda picos e suavização, o cliente com picos pode dominar a concorrência partilhada, empurrando o cliente estável para timeouts. Um bom limitador torna o comportamento mais previsível e reduz a necessidade de autoscaling agressivo que apenas mascara o problema.

Escolher limites que correspondem a gargalos reais do sistema

A primeira escolha de desenho é a unidade que vai limitar. “Pedidos por segundo” é fácil de medir, mas pode enganar quando os pedidos têm custos muito diferentes. Na prática, muitas equipas introduzem limites ponderados: uma leitura barata pode custar 1 unidade, uma pesquisa complexa pode custar 5, e uma exportação em lote pode custar 20. Assim, a limitação de taxa alinha-se com o gargalo real — CPU, IO de base de dados ou uma quota de terceiros — em vez de um simples contador de pedidos.

Depois vem o escopo: por IP, por chave de API, por conta de utilizador, por organização, ou por credencial + endpoint. Limites só por IP são fáceis de contornar e podem penalizar redes corporativas com NAT. Limites só por chave podem ser explorados se a chave vazar. A abordagem mais robusta para APIs públicas costuma ser em camadas: salvaguardas moderadas por IP para reduzir varrimentos óbvios, controlos mais fortes por chave/conta para justiça e, opcionalmente, limites por rota para endpoints conhecidos por serem caros.

A escolha da janela temporal também é uma escolha de fiabilidade. Janelas muito curtas (por segundo) ajudam contra picos repentinos, enquanto janelas longas (por minuto/hora/dia) controlam consumo sustentado. Muitos desenhos de produção usam, de forma intencional, pelo menos duas janelas em conjunto: um limitador de curto prazo que protege a capacidade instantânea e uma quota de longo prazo que impõe o contrato de utilização.

Token bucket vs leaky bucket: picos, suavização e detalhes de implementação

Token bucket e leaky bucket são frequentemente apresentados como alternativas concorrentes, mas em sistemas reais resolvem problemas diferentes. O token bucket foi pensado para permitir picos: os tokens acumulam até uma capacidade máxima, e cada pedido consome tokens. Se um cliente esteve “quieto”, pode acumular capacidade e, depois, enviar um pico curto sem ser bloqueado. Isto combina bem com comportamentos humanos e de máquinas — apps acordam, filas descarregam, parceiros enviam lotes — e evita penalizar clientes por padrões naturais de tráfego.

O leaky bucket, por outro lado, é sobre suavização. Pode imaginá-lo como uma fila que escoa a uma taxa constante. Se os pedidos chegam mais rápido do que a taxa de escoamento, a fila enche e o excesso é atrasado ou rejeitado. Este modelo é especialmente útil quando o recurso protegido reage mal a carga “aos solavancos”: uma base de dados que “cai do penhasco” quando há picos de ligações, ou um serviço a jusante com capacidade estrita por segundo.

Na prática, engenheiros implementam token bucket na borda (API gateway, reverse proxy, ingress) e uma suavização tipo leaky bucket mais perto do gargalo (fila de workers, executor de jobs por inquilino, pooler de base de dados). O limitador na borda protege o serviço de enxurradas súbitas, enquanto a suavização interna protege as partes frágeis de tráfego irregular que ainda passou.

Erros comuns: limites distribuídos, deriva do relógio e falsos positivos

Um erro clássico é tentar impor um único limitador global em muitos nós sem pensar em consistência. Se cada nó impõe “100 pedidos/segundo” de forma independente, o limite efetivo torna-se “100 por nó”. Para evitar isso, precisa de estado partilhado (por exemplo, um armazenamento central) ou de uma estratégia deliberada como limites locais + uma quota global verificada com menor frequência. Em 2026, ainda é comum aceitar aplicação aproximada na borda, porque a precisão global perfeita muitas vezes custa mais em latência e complexidade do que o ganho marginal de justiça.

Assunções sobre relógio e janelas de tempo também podem causar problemas. Janelas deslizantes, janelas fixas e calendários de reposição de tokens comportam-se de forma diferente em fronteiras. Janelas fixas (por exemplo, reset a cada minuto) criam efeitos de borda em que clientes disparam às 12:00:00. Janelas deslizantes reduzem isso, mas podem ser mais pesadas de calcular. Token bucket evita parte desses artefactos, mas ainda é preciso escolher a granularidade de reposição e decidir se os tokens reabastecem continuamente ou em “ticks”.

Falsos positivos quase sempre vêm da identidade e da topologia de rede, não do algoritmo em si. NAT, gateways de operadoras móveis e proxies corporativos podem fazer muitos utilizadores parecerem um único IP. Por outro lado, redes de bots podem fazer um único ator parecer muitos IPs. Se confiar apenas em limites por IP, corre o risco de bloquear utilizadores reais enquanto mal abranda o abuso. Se confiar apenas em chaves de API, uma chave vazada pode causar danos sustentados. Limites em camadas e deteção de anomalias — uso súbito de uma chave a partir de novas regiões, endpoints invulgares ou taxas extremas de erro — tendem a reduzir ambos os tipos de erro.

Quotas e backoff: transformar “throttling” num contrato estável

Limitação de taxa sem feedback claro cria comportamento confuso do lado do cliente: repetições em loop apertado, atrasos aleatórios ou lógica de “tentar de novo” espalhada pelo código. As quotas formalizam o que “uso justo” significa ao longo de períodos maiores — por minuto, hora ou dia — e permitem oferecer escalões ou alocações a parceiros. As quotas também ajudam na resposta a incidentes: durante uma degradação parcial pode reduzir alocações temporariamente, proteger clientes críticos e impedir que o sistema entre em oscilação enquanto recupera.

O backoff é o que impede as repetições de virarem um amplificador. Quando serviços degradam, a latência sobe e as taxas de erro aumentam. Clientes que repetem de imediato adicionam ainda mais carga, piorando a situação. Backoff exponencial com jitter é a abordagem padrão em 2026 porque espalha as repetições ao longo do tempo e evita “tempestades” sincronizadas. A parte do jitter é essencial: se todos os clientes duplicarem atrasos em sincronia, continuam a colidir.

Para quotas e backoff funcionarem em conjunto, precisa de sinalização consistente. Quando limitar, devolva um estado apropriado (frequentemente HTTP 429) e, quando possível, inclua orientação como quanto tempo esperar. Sinais claros e previsíveis permitem que SDKs de cliente implementem repetições seguras de forma centralizada, em vez de cada integrador ter de adivinhar o comportamento correto.

Desenho prático de respostas: 429, headers e comportamento do cliente

Uma boa resposta de limitação é explícita e amiga de máquinas. Em APIs HTTP, o 429 é amplamente usado para indicar que o cliente excedeu um limite, e muitos clientes já o reconhecem. Incluir um header Retry-After é útil quando consegue calcular um atraso razoável. Mesmo quando não dá para ser exato, um valor conservador pode evitar martelar imediatamente e reduzir tráfego desperdiçado.

Também ajuda publicar limites como parte do contrato para que os clientes se auto-regulem. Muitas APIs expõem contadores de limite e “restante” via headers de resposta ou documentação para programadores. Aqui, atenção à semântica: “restante” pode ser por minuto, por hora ou por janela móvel, e os clientes vão comportar-se mal se adivinharem errado. Se usar vários limitadores (pico por segundo e quota por dia), deixe claro qual sinal corresponde a qual restrição.

Do lado do cliente, comportamento seguro normalmente inclui: backoff exponencial com jitter, um teto máximo para o atraso, um máximo de tentativas e idempotência para operações que podem ser repetidas. Para operações de escrita, chaves de idempotência costumam ser a diferença entre “uma repetição é inofensiva” e “uma repetição duplica um pagamento”. Trate backoff como parte da correção, não apenas desempenho: protege o seu serviço, mas também protege utilizadores de ações duplicadas e de falhas parciais confusas.