Rate limiting moderno: RateLimit headers e orçamento de latência

Introdução: Rate limiting é um contrato de capacidade, não punição

Rate limiting é frequentemente tratado como um mecanismo de defesa bruto: uma parede que rejeita requisições depois que um limiar é cruzado. Na realidade, rate limiting bem projetado é um contrato de capacidade entre o provedor da API e seus consumidores. Ele comunica: "aqui está quanto você pode usar, aqui está quanto resta, e aqui está quanto tempo até seu orçamento resetar."

Quando esse contrato é implícito (não documentado, sinalizado apenas por um 429 Too Many Requests repentino), os consumidores reagem de forma inadequada. Eles implementam loops agressivos de retry sem backoff, criando tempestades de retry que amplificam justamente a sobrecarga que o rate limit tentava prevenir. Um único pico pode cascatear em degradação prolongada do serviço.

O padrão emergente do IETF para headers RateLimit (draft-ietf-httpapi-ratelimit-headers) resolve isso tornando o comportamento de cota legível por máquina. Consumidores podem adaptar programaticamente seu comportamento antes de atingir limites, em vez de reagir depois de serem rejeitados.

Como os headers RateLimit funcionam

O draft do IETF padroniza um conjunto de headers de resposta que comunicam o estado da cota em cada resposta — não apenas nas rejeições 429.

Headers principais

HTTP/1.1 200 OK
RateLimit-Limit: 100
RateLimit-Remaining: 42
RateLimit-Reset: 30

Quando o limite é excedido

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 18
Retry-After: 18

O header Retry-After (da RFC 9110) diz ao consumidor exatamente quantos segundos esperar antes de tentar novamente. Esse único header, quando respeitado, elimina por completo a possibilidade de tempestades de retry.

A anatomia de uma tempestade de retry

Entender _por que_ tempestades de retry são tão destrutivas é crucial para apreciar o valor do rate limiting explícito.

1. O gatilho: Um pico legítimo de tráfego faz a latência P95 aumentar.
2. A amplificação: Consumidores experimentam timeouts. Sem orientação de Retry-After, eles retentam imediatamente, frequentemente com paralelismo (Promise.all de requisições retentadas).
3. A cascata: Os retries adicionam 2-3x de carga sobre o pico original. O servidor, já sob pressão, começa a rejeitar ainda mais requisições.
4. A espiral da morte: Mais rejeições → mais retries → mais rejeições. O serviço se torna efetivamente indisponível apesar do rate limiter estar funcionando corretamente.

A solução: Quando a API retorna RateLimit-Remaining: 0 e Retry-After: 18, clientes bem-comportados pausam por 18 segundos. A tempestade nunca se forma. O servidor se recupera naturalmente dentro da janela de reset.

Aprofundando a análise: Projetando políticas de rate limit

Um limite global único para todos os endpoints está quase sempre errado. Diferentes operações têm custos vastamente diferentes:

Política por classe de operação

Quotas por tenant

Em ambientes multi-tenant, throttling baseado em IP é injusto. Um grande cliente corporativo operando atrás de um único IP compartilhará seu limite com milhares de funcionários. Em vez disso, rate limits devem ser baseados em tokens de autenticação (API keys, claims do JWT), garantindo que cada tenant receba sua capacidade contratada independentemente da topologia de rede.

Políticas hierárquicas

Sistemas maduros de rate limiting implementam múltiplas camadas com procedência explícita:

1. Limite global da plataforma: Protege a infraestrutura como um todo (ex: 50.000 req/s em todos os consumidores).
2. Limite por tenant: Capacidade contratual para cada consumidor de API (ex: 1.000 req/min para parceiros tier-1).
3. Limite por endpoint: Previne abuso de operações caras dentro da cota geral de um tenant.

A dimensão do orçamento de latência

Rate limiting endereça _volume_. Mas volume não é a única ameaça aos SLOs. Um único endpoint lento pode consumir recursos desproporcionais do servidor (pool de threads, conexões de banco), degradando endpoints não relacionados.

Orçamentos de latência complementam rate limits endereçando _tempo_:

• Se uma requisição não completou dentro do seu orçamento de latência (ex: 500ms para leitura, 2s para escrita), o servidor deve descartá-la — retornando um 503 Service Unavailable com Retry-After — em vez de deixá-la consumir recursos indefinidamente.
• Isso previne que uma única query lenta trave o serviço inteiro.

Combinados com rate limits, orçamentos de latência criam um sistema de proteção bidimensional: limitando tanto a quantidade quanto a duração da capacidade consumida.

Quando rate limiting acelera a entrega

Tratar rate limits como contratos explícitos e legíveis por máquina gera ganhos compostos de estabilidade:

• Política por classe de operação: Leituras leves, escritas pesadas e jobs assíncronos recebem limites calibrados individualmente.
• Quotas por tenant: Evita o throttling injusto baseado apenas em IP usando tokens de autenticação.
• Sinalização explícita de cota: Status codes e headers orientam proativamente o comportamento do consumidor.

Perguntas de decisão para o seu contexto de engenharia:

• Quais limites devem ser baseados em token, IP ou recurso para reduzir abuso lateral?
• Como o orçamento restante será exposto para que clientes adaptem seu comportamento antes de serem rejeitados?
• Quais rotas precisam de políticas elásticas que mudam por horário do dia ou eventos de negócio (ex: Black Friday)?

Roteiro de otimização contínua

1. Classifique endpoints por custo e criticidade. Nem todos são iguais. Um GET /health e um POST /pedidos nunca devem compartilhar o mesmo rate limit.
2. Defina políticas de cota por tenant e por operação. Use contexto de autenticação (API key, JWT) para aplicar limites justos.
3. **Emita headers RateLimit e RateLimit-Policy em todas as APIs client-facing.** Toda resposta — não apenas 429s — deve incluir o estado atual da cota.
4. Publique orientação formal de retry/backoff. Documente o comportamento esperado do cliente: respeitar Retry-After, implementar backoff exponencial com jitter.
5. Alerte sobre taxa de rejeição E latência de cauda. Monitorar apenas respostas 429 perde a saturação de latência que precede a sobrecarga.
6. Simule tráfego de burst e degradação controlada. Testes de carga regulares devem validar que rate limiter, circuit breakers e load shedding funcionam juntos sob condições realistas.

Como validar evolução em produção

Meça o sucesso da governança de rate limiting monitorando:

• Taxa de 429 por rota e perfil de consumidor: Quais consumidores estão atingindo limites mais frequentemente? Os limites estão corretamente calibrados?
• Latência P95/P99 durante picos de tráfego: A latência de cauda melhorou agora que controles de budget previnem sobrecarga?
• Incidentes de capacidade prevenidos: Quantas potenciais indisponibilidades foram evitadas porque o rate limiter ativou e consumidores respeitaram o Retry-After?

Quer transformar esse plano em execução com previsibilidade técnica e impacto no negócio? Falar com especialista em web com a Imperialis para desenhar, implementar e operar essa evolução.

Fontes

• IETF HTTPAPI RateLimit Draft
• RateLimit Header Draft HTML
• RFC 9110 HTTP Semantics