Rate Limiting API: Guia de Implementação Passo a Passo

Rate limiting é uma técnica que restringe o número de requisições que um cliente pode fazer a uma API em um intervalo de tempo. Para implementar, defina limites por chave de API ou IP, use um armazenamento como Redis e retorne o status HTTP 429 quando o limite for excedido.

Este guia mostra o caminho para proteger sua API contra abusos e sobrecarga. O resultado esperado é uma API que responde de forma previsível, mesmo sob picos de tráfego. Antes de começar, você precisa de uma aplicação com rotas HTTP definidas e acesso a um armazenamento de dados rápido, como Redis ou até mesmo a memória do servidor para testes iniciais.

Passo 1: Escolha a estratégia de limite

A primeira decisão é qual algoritmo usar. O mais simples é o fixed window: define um contador que zera a cada janela fixa, por exemplo, 100 requisições por minuto. O sliding window é mais preciso, pois considera o histórico contínuo de requisições, evitando picos no início de cada janela. Já o token bucket permite rajadas controladas: cada requisição consome um token, e tokens são repostos a uma taxa constante.

Para a maioria dos casos, o token bucket oferece bom equilíbrio entre simplicidade e flexibilidade. Um erro comum é usar apenas o IP como identificador. Em redes corporativas ou com NAT, muitos usuários compartilham o mesmo IP, e o limite pode ser atingido por um único cliente, bloqueando os demais. Prefira combinar IP com chave de API, quando disponível.

Passo 2: Defina os limites por cliente

Limites não devem ser iguais para todos. Um plano gratuito pode permitir 10 requisições por minuto, enquanto um plano pago permite 1.000. Defina os limites em um arquivo de configuração ou no banco de dados, associados ao plano do cliente. Isso permite ajustes sem alterar o código.

Uma dica: comece com limites conservadores e aumente gradualmente, monitorando o uso real. Um erro comum é definir limites altos para evitar reclamações, o que torna o rate limiting inútil. O objetivo é proteger a API, não apenas cumprir um requisito técnico.

Passo 3: Implemente o contador com armazenamento atômico

O contador precisa ser atômico para evitar condições de corrida. Em Redis, use o comando INCR com expiração via EXPIRE. O pseudocódigo abaixo ilustra a lógica:

chave = "rate:" + cliente_id + ":" + janela_atual contador = INCR(chave) if contador == 1: EXPIRE(chave, duracao_janela) if contador > limite: retornar 429

Se você estiver usando um banco relacional, use transações com SELECT ... FOR UPDATE para evitar incrementos simultâneos. Um erro comum é implementar o contador na memória da aplicação em múltiplas instâncias: cada instância teria um contador separado, e o limite global não seria respeitado. Por isso, o armazenamento deve ser compartilhado.

Passo 4: Retorne cabeçalhos de limite e status 429

Quando o limite é excedido, a resposta deve incluir o status HTTP 429 Too Many Requests e, de preferência, o cabeçalho Retry-After com o tempo em segundos até o próximo reset. Isso permite que o cliente saiba quando pode tentar novamente.

Além disso, inclua cabeçalhos informativos em todas as respostas: X-RateLimit-Limit (limite máximo), X-RateLimit-Remaining (requisições restantes) e X-RateLimit-Reset (timestamp do reset). Um erro comum é omitir esses cabeçalhos, deixando o cliente sem visibilidade sobre o uso. Isso gera retries desnecessários e frustração.

Passo 5: Teste e monitore o comportamento

Antes de colocar em produção, teste com cargas simuladas. Ferramentas como Apache Bench ou k6 podem gerar requisições acima do limite e verificar se as respostas 429 são emitidas corretamente. Monitore também a taxa de erros e o tempo de resposta para ajustar os limites.

Um erro comum é não testar o comportamento em múltiplas instâncias da aplicação. Se você usa um load balancer, certifique-se de que o armazenamento compartilhado (Redis) está configurado corretamente. Em um teste simples, um contador por instância pode mascarar problemas de escalabilidade.

Checklist final

• Estratégia de limite definida (token bucket, sliding window ou fixed window).
• Limites configurados por cliente ou plano, não apenas por IP.
• Contador atômico em armazenamento compartilhado (Redis ou banco com transações).
• Respostas 429 com cabeçalho Retry-After.
• Cabeçalhos X-RateLimit-* presentes em todas as respostas.
• Testes de carga realizados com múltiplas instâncias.

Com esses passos, sua API está protegida contra abusos e sobrecarga. O próximo passo é revisar as métricas de uso semanalmente e ajustar os limites conforme o comportamento real dos clientes.

Perguntas frequentes

O que é rate limiting em API?

Rate limiting é um mecanismo que controla quantas requisições um cliente pode fazer a uma API em um período de tempo. Ele previne abusos, protege a infraestrutura e garante uso justo entre consumidores.

Qual a diferença entre rate limiting e throttling?

Rate limiting bloqueia requisições que excedem o limite, retornando erro 429. Throttling, por outro lado, atrasa ou reduz a velocidade das requisições, permitindo que o cliente continue, mas de forma controlada.

O que é o status HTTP 429?

O status 429 Too Many Requests indica que o cliente excedeu o número permitido de requisições em um intervalo de tempo. A resposta deve incluir o cabeçalho Retry-After informando quando tentar novamente.

Onde devo armazenar os contadores de rate limiting?

Use um armazenamento compartilhado e atômico, como Redis. Em aplicações com múltiplas instâncias, a memória local não é suficiente, pois cada instância teria um contador independente, ignorando o limite global.

Rate limiting deve ser aplicado por IP ou por chave de API?

O ideal é combinar ambos. O IP sozinho pode bloquear usuários legítimos atrás de NAT. A chave de API permite diferenciar planos e identificar o cliente. Em casos de abuso, o IP pode ser usado como fallback.

Como escolher o limite de requisições?

Comece com limites conservadores baseados no uso médio dos clientes e aumente gradualmente. Monitore a taxa de erros 429 e o tráfego real para ajustar. Limites muito altos tornam o rate limiting ineficaz.