Erro 429 Too Many Requests: como resolver em sites, APIs e agentes

Resposta rápida

Erro 429 Too Many Requests significa que o cliente enviou solicitações demais dentro do período aceito pelo servidor. É uma resposta de limitação de taxa, também chamada de rate limit, e não prova que o site ou a API inteira caiu.

Se você é visitante, pare de atualizar a página repetidamente e aguarde antes de testar de novo. Se administra uma integração, leia o corpo e os cabeçalhos da resposta, respeite Retry-After quando ele existir e limite concorrência e novas tentativas. Um robô que insiste imediatamente pode manter o bloqueio ativo e consumir ainda mais capacidade.

O que o visitante pode fazer

Um 429 pode atingir apenas uma conta, endereço IP, rota ou ação. Várias abas abertas, atualizações repetidas, extensões, VPN compartilhada e automações no mesmo acesso podem somar solicitações sem que isso fique evidente na tela.

• Pare de recarregar a página e feche abas duplicadas do mesmo serviço.
• Aguarde o período informado na mensagem ou no cabeçalho Retry-After, quando ele estiver visível.
• Confirme se outro recurso do serviço abre normalmente para separar uma rota limitada de uma indisponibilidade ampla.
• Se usa VPN ou proxy corporativo, considere que outras pessoas podem compartilhar o mesmo endereço IP e o mesmo limite.
• Evite trocar de rede para contornar uma proteção legítima. Se o bloqueio persistir além do prazo indicado, registre horário, URL e conta e procure o suporte.

Como ler Retry-After e os cabeçalhos de limite

O RFC 6585 permite que uma resposta 429 inclua Retry-After para indicar quando uma nova tentativa pode ser feita. O valor pode representar um número de segundos ou uma data HTTP, conforme a definição do cabeçalho.

Cada provedor pode publicar cabeçalhos adicionais com limite, capacidade restante e horário de renovação. Não suponha nomes ou unidades: leia a documentação da API e preserve o corpo completo da resposta. Quando Retry-After não existe, aplique uma pausa progressiva e um número máximo de tentativas em vez de repetir imediatamente.

Checklist para diagnosticar o 429 numa API

A primeira pergunta não é como aumentar o limite, mas qual limite foi atingido. A restrição pode ser por usuário, token, endereço IP, organização, endpoint, janela de tempo, volume concorrente ou custo da operação.

• Registre endpoint, método, status, horário, identificador da requisição, corpo e cabeçalhos sem expor tokens.
• Confira se a API informa Retry-After, capacidade restante ou horário de renovação da janela.
• Some todas as instâncias, funções, filas e agentes que compartilham a mesma credencial ou conta.
• Separe limite por período de excesso de concorrência e de cota contratada, pois cada caso exige uma correção diferente.
• Verifique se a aplicação está duplicando chamadas, repetindo paginação ou consultando o mesmo dado sem cache.
• Reproduza com uma solicitação isolada depois da janela indicada antes de alterar credenciais ou contratar mais capacidade.

Como implementar novas tentativas sem criar um loop

A nova tentativa precisa ser limitada e coordenada. Se dezenas de processos voltam ao mesmo tempo, o pico se repete assim que a janela abre. Use atraso progressivo com uma pequena variação aleatória, conhecida como jitter, para distribuir as chamadas.

• Respeite Retry-After antes de calcular qualquer atraso próprio.
• Quando o provedor permitir novas tentativas sem Retry-After, aumente o intervalo a cada falha e acrescente jitter.
• Defina quantidade máxima de tentativas e um prazo total para abandonar a operação com erro claro.
• Não repita automaticamente operações não idempotentes, como cobrança, criação de pedido ou envio de mensagem, sem uma chave de idempotência compatível.
• Centralize a fila e o controle de concorrência para que cada processo não interprete o limite de forma isolada.
• Use cache, eliminação de duplicatas, paginação correta e processamento em lote quando a API oferecer essas opções.

Erro 429 em agentes de IA e automações

Agentes podem transformar um erro temporário em uma tempestade de chamadas quando tentam novamente a mesma ferramenta, abrem tarefas paralelas ou reiniciam o plano sem considerar as tentativas anteriores. O controle de taxa precisa ficar numa camada compartilhada, não apenas no texto de instrução do agente.

Defina orçamento de chamadas por execução, limite de concorrência, fila central, tentativas máximas e estado persistente da janela de espera. O agente deve devolver um erro compreensível quando o limite for alcançado e nunca aumentar privilégios, trocar credenciais ou contratar mais cota sem autorização.

O que observar na API do GitHub

A documentação do GitHub consultada em 1º de setembro de 2026 informa que limites primários e secundários podem produzir resposta 403 ou 429. Quando x-ratelimit-remaining chega a zero, a integração deve aguardar o horário indicado por x-ratelimit-reset. Se Retry-After estiver presente, a espera indicada precisa ser respeitada.

O GitHub também recomenda evitar solicitações concorrentes em excesso e interromper as tentativas após um número definido de falhas. Continuar enviando chamadas durante a limitação pode resultar em bloqueio da integração.

Checklist para quem protege um site com rate limiting

O limite precisa conter abuso sem bloquear usuários legítimos. Antes de aumentar o valor ou desligar a regra, identifique a rota, o padrão de tráfego, o identificador do cliente e a duração do bloqueio.

• Separe páginas comuns, login, recuperação de senha, formulários e APIs por risco e custo.
• Use uma resposta 429 clara e inclua Retry-After quando houver um prazo confiável para nova tentativa.
• Monitore falsos positivos por rota, região, rede compartilhada e tipo de cliente.
• Evite limites globais tão amplos que um único consumidor afete todos os usuários.
• Teste a regra com tráfego legítimo e abusivo antes de ampliar uma exceção.

Limites do diagnóstico externo

Uma consulta pública isolada pode receber 200 enquanto a sua conta ou credencial continua limitada. O teste externo não conhece automaticamente a janela, o token, a cota contratada nem as chamadas feitas por outras instâncias.

Também é possível que o provedor devolva 403 para determinados limites. Por isso, o código precisa ser interpretado junto com corpo, cabeçalhos e documentação oficial, sem concluir que toda resposta 403 é permissão ou que todo 429 é uma queda do serviço.

Próxima ação útil

Se o erro apareceu num site, pare as atualizações e compare a URL no diagnóstico web do Caiu ou Não?. Se ocorreu numa API ou agente, salve a resposta completa sem o token, identifique a janela e pause as chamadas conforme Retry-After. Depois, corrija concorrência, duplicação e fila antes de solicitar aumento de limite.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• 429 Too Many RequestsMDN Web Docs
• RFC 6585, seção 429RFC Editor
• Rate limits for the REST APIGitHub Docs
• Best practices for using the REST APIGitHub Docs
• Error 429Cloudflare Docs
• Rate limiting headers on the Cloudflare APICloudflare Changelog