HTTP 429 Too Many Requests: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, ferramenta de monitoramento ou verificador recebe 429 Too Many Requests.
• A resposta pode afetar uma URL, rota de API, método HTTP, endereço IP, conta ou cliente específico, em vez do site inteiro.
• As solicitações podem voltar a funcionar após um intervalo, o que é compatível com um rate limit temporário.
• A resposta pode incluir Retry-After ou outros cabeçalhos relacionados a rate limiting.
• O DNS pode resolver e o TLS pode ser concluído porque a solicitação chegou a um endpoint que fala HTTP; essas verificações não provam que a solicitação é permitida na camada da aplicação.
• Clientes ou redes diferentes podem receber resultados diferentes quando o limite é definido por IP, identidade, token ou sessão.

Causas principais, por probabilidade

1. Um limite de taxa de solicitações foi excedido. A aplicação, o gateway de API ou o servidor web pode limitar as solicitações por endereço IP, conta, sessão, chave de API, rota ou outra identidade do cliente.
2. Um proxy, CDN ou WAF aplicou sua própria política. Um intermediário pode retornar 429 antes que a solicitação chegue ao servidor de origem.
3. O tráfego automatizado está enviando solicitações rápido demais. Crawlers, verificações de monitoramento, scripts, novas tentativas ou workers paralelos podem acionar um limite mesmo quando as solicitações individuais parecem válidas.
4. Um cliente está tentando novamente sem backoff. Tentativas repetidas após falhas podem manter o cliente dentro da janela do limite ou intensificar a carga.
5. Uma configuração ou implantação alterou o limite efetivo. Uma regra recente, mudança de roteamento, integração de autenticação ou política de proxy pode ter alterado quais solicitações são contabilizadas ou limitadas.
6. O limite é intencional, mas o fluxo de trabalho do cliente é incompatível com ele. Por exemplo, um processo em lote pode precisar de cadência, reutilização de conexões ou uma cota de solicitações aprovada, em vez de novas tentativas imediatas e repetidas.

Como corrigir

Para visitantes e consumidores de APIs

1. Interrompa atualizações rápidas, solicitações paralelas e novas tentativas automáticas enquanto investiga o problema.
2. Verifique os cabeçalhos de resposta em busca de Retry-After. Se estiver presente, aguarde o intervalo ou horário indicado antes de tentar novamente.
3. Tente novamente a URL ou o endpoint de API exato, usando o mesmo método, após o intervalo. Não troque de método nem varie repetidamente as solicitações apenas para escapar do limite.
4. Se você controla o cliente, use novas tentativas limitadas com exponential backoff e jitter, respeitando a cota de solicitações documentada pelo serviço. Evite repetir solicitações que não sejam seguras para repetição, a menos que a API defina como elas devem ser repetidas.
5. Verifique se o problema afeta um cliente, conta, chave de API, rede ou endpoint específico. Um resultado diferente em outro cliente, por si só, não identifica a causa.
6. Se o 429 persistir, entre em contato com o proprietário do site ou da API informando o endpoint, método, timestamp, cabeçalhos de resposta e uma descrição da frequência das solicitações. Remova cookies, valores de autorização e secrets de API de tudo o que compartilhar.

Para proprietários de sites e desenvolvedores

1. Reproduza a resposta com o menor teste autorizado que corresponda ao método, URL, identidade do cliente e taxa de solicitações afetados. Registre o status, o timestamp e os cabeçalhos de resposta relevantes.
2. Identifique a camada que gerou a resposta. Verifique os detalhes da resposta da CDN ou do WAF, os logs do proxy reverso, os logs do servidor web e os logs da aplicação na ordem correspondente à sua arquitetura. Não presuma que a origem gerou a resposta.
3. Pesquise nos logs relevantes o mesmo timestamp, rota, identificador do cliente e decisão de rate limiting. Determine o que está sendo contabilizado e qual janela ou política de limite foi aplicada.
4. Compare a solicitação afetada com uma solicitação normal. Verifique o método HTTP, o contexto de autenticação, a identidade de origem, a rota, o caminho de cache e alterações recentes de implantação ou configuração.
5. Se o limite for intencional, melhore as orientações para o cliente: retorne um valor preciso de Retry-After quando apropriado, documente as cotas e garanta que os clientes possam usar backoff controlado em vez de loops de novas tentativas rápidas.
6. Se o limite estiver incorreto, aplique a correção autorizada mais específica possível na camada que gerou a resposta. Valide o efeito na rota afetada sem enfraquecer proteções de segurança ou contra abuso não relacionadas.
7. Teste novamente a mesma solicitação e taxa e, em seguida, teste rotas vizinhas e identidades de cliente representativas. Confirme que os limites intencionais continuam funcionando e que a resposta não bloqueia mais tráfego legítimo.

Prevenção e como verificar a correção

• Defina e documente cotas de solicitações, escopo dos limites e comportamento de novas tentativas para APIs e clientes automatizados.
• Retorne informações úteis sobre rate limiting, incluindo Retry-After quando apropriado e compatível com o design do serviço.
• Implemente exponential backoff limitado com jitter nos clientes, em vez de novas tentativas imediatas e repetidas.
• Monitore as taxas de 429 por rota, identidade do cliente, rede e implantação para distinguir aumentos amplos de abuso isolado ou clientes com comportamento inadequado.
• Mantenha as configurações de rate limiting da CDN, WAF, proxy, servidor e aplicação sob controle de versão e revise as alterações antes da liberação.
• Teste métodos de API importantes e rotas públicas após as implantações, incluindo o comportamento esperado quando um limite é atingido.
• Mantenha logs suficientes e sanitizados de solicitações e decisões de política para associar uma resposta 429 ao componente que a gerou.

Perguntas frequentes