Como Corrigir o Erro '429 Too Many Requests' na Sua Aplicação Web

Sua aplicação web para de funcionar repentinamente. As chamadas à API falham. Os usuários veem erros. O culpado? HTTP 429 Too Many Requests—a forma do servidor dizer à sua aplicação para desacelerar.

Este guia explica o que causa erros 429 em aplicações web modernas, como interpretar os sinais que os servidores enviam e estratégias práticas de limitação de requisições no frontend que previnem esses erros.

O Que HTTP 429 Too Many Requests Realmente Significa

O código de status 429 indica que seu cliente excedeu os limites de taxa definidos por um servidor. Diferentemente de erros da série 500 (problemas do servidor) ou 503 Service Unavailable (sobrecarga temporária), um 429 é explícito: você está fazendo muitas requisições e o servidor está se protegendo.

A limitação de taxa de API pode se originar de múltiplas fontes:

• Seu próprio backend aplicando limites por usuário ou por sessão
• CDNs e WAFs bloqueando padrões de tráfego que parecem abusivos
• APIs de terceiros protegendo sua infraestrutura de chamadas excessivas

Cada fonte pode ter limites diferentes, janelas de detecção diferentes e comportamentos de recuperação diferentes. Uma única ação do usuário em sua aplicação pode disparar requisições para vários serviços, qualquer um dos quais pode retornar um 429.

Entendendo os Cabeçalhos de Limite de Taxa

Quando servidores implementam limitação de taxa, frequentemente comunicam limites através de cabeçalhos de resposta. Existem dois padrões:

Cabeçalhos legados usam o prefixo X-RateLimit-*:

• X-RateLimit-Limit: Máximo de requisições permitidas
• X-RateLimit-Remaining: Requisições restantes na janela atual
• X-RateLimit-Reset: Quando o limite é reiniciado (geralmente timestamp Unix)

Cabeçalhos padronizados seguem o formato mais recente RateLimit e RateLimit-Policy, que fornece informações similares com semântica melhor definida.

Nem toda API usa esses cabeçalhos. Algumas retornam apenas o status 429 sem contexto adicional. Seu código deve lidar com ambos os cenários.

O Cabeçalho Retry-After

O cabeçalho Retry-After informa aos clientes quando eles podem tentar novamente com segurança. Ele aparece em dois formatos:

Retry-After: 120                            // segundos para esperar
Retry-After: Wed, 21 Oct 2025 07:28:00 GMT  // timestamp específico

Quando presente, respeite-o. Quando ausente, implemente backoff exponencial—espere progressivamente mais tempo entre retries (1 segundo, depois 2, depois 4, e assim por diante).

Alguns servidores omitem Retry-After completamente. Outros o incluem de forma inconsistente. Construa sua lógica de retry para funcionar sem ele, mas honrando-o quando disponível.

Estratégias de Limitação de Requisições no Frontend

A maioria dos erros 429 em aplicações com frontend pesado deriva de interações de UI disparando chamadas excessivas à API. Veja como preveni-los:

Debounce em Entrada do Usuário

Caixas de busca, campos de autocompletar e filtros frequentemente disparam requisições a cada tecla digitada. Debouncing espera até que o usuário pare de digitar antes de enviar a requisição:

function debounce(func, delay) {
  let timeoutId;
  return function (...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => func.apply(this, args), delay);
  };
}

// Espera 300ms após a última tecla digitada antes de buscar
const debouncedSearch = debounce(searchAPI, 300);

Agrupe Requisições Relacionadas

Ao invés de buscar dados para cada item individualmente, combine requisições onde as APIs suportarem. Uma requisição para 50 itens é melhor que 50 requisições individuais.

Cache Agressivo

Armazene respostas que não mudam com frequência. Antes de fazer uma requisição, verifique se você já tem dados válidos em cache. Isso se aplica tanto a caches do navegador quanto a cache no nível da aplicação.

Respeite os Sinais de Limite de Taxa

Quando você receber cabeçalhos de limite de taxa, use-os proativamente. Se X-RateLimit-Remaining mostrar que você está quase esgotado, desacelere antes de atingir o limite.

Lidando com Erros 429 de Forma Elegante

Quando um 429 ocorre apesar dos esforços de prevenção:

1. Analise a resposta em busca de Retry-After ou cabeçalhos de limite de taxa
2. Enfileire a requisição que falhou para retry após o atraso especificado
3. Informe os usuários apropriadamente—mostre um estado de carregamento, não um erro
4. Registre a ocorrência para identificar padrões em seu monitoramento

Evite retries imediatos. Sobrecarregar um servidor que acabou de dizer para você desacelerar piora as coisas e pode disparar bloqueios mais longos.

Note que alguns CDNs e WAFs aplicam janelas de cooldown fixas, significando que retries podem ser bloqueados por minutos independentemente da lógica de backoff no lado do cliente.

Distinguindo 429 de Outros Erros

Um 429 requer espera. Um 503 pode se resolver rapidamente ou indicar uma interrupção maior. Um 500 sugere um bug. Seu tratamento de erros deve diferenciar:

• 429: Recue, espere, tente novamente com o atraso especificado
• 503: Tente novamente com backoff, mas monitore por interrupções prolongadas
• 500: Registre o erro, possivelmente tente uma vez, depois falhe elegantemente

Conclusão

HTTP 429 Too Many Requests é um sinal de limitação de taxa, não uma falha. Previna-o através de limitação de requisições no frontend—debouncing, agrupamento e cache. Quando acontecer, respeite o cabeçalho Retry-After e implemente backoff exponencial.

A melhor correção para erros 429 é nunca dispará-los. Projete sua aplicação para fazer apenas requisições necessárias, e você raramente verá esse erro em produção.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.