HTTP 429 Too Many Requests

O que significa o HTTP 429

HTTP 429 Too Many Requests significa que o cliente excedeu um limite de requisições — por IP, por chave de API, por usuário ou por endpoint. Servidores bem comportados incluem um cabeçalho Retry-After (segundos ou uma data) e frequentemente cabeçalhos X-RateLimit-* descrevendo a cota.

Para os clientes, a reação correta é sempre a mesma: desacelerar. Tentar novamente imediatamente piora a situação e pode transformar uma limitação temporária em um banimento.

Causas comuns de erros 429

• Um cliente de API consulta com muita frequência ou explode acima de sua cota.
• Web scraping sem atrasos entre requisições.
• Um bug: um loop de nova tentativa sem backoff martelando o mesmo endpoint.
• IP compartilhado (NAT de escritório, VPN, saída serverless) onde o tráfego combinado ultrapassa o limite.
• Endpoints de login limitando tentativas repetidas como proteção contra força bruta.

Como corrigir como cliente/desenvolvedor

• Respeite exatamente o Retry-After; se ausente, use backoff exponencial com jitter (por exemplo, 1s, 2s, 4s, 8s…).
• Leia os cabeçalhos X-RateLimit-Remaining/Redefinir da API e ritme as requisições proativamente.
• Agrupe requisições e armazene respostas em cache em vez de buscar novamente dados idênticos.
• Distribua a carga ao longo do tempo, não entre IPs descartáveis — burlar limites geralmente viola os termos da API.

Como corrigir como proprietário de API

• Sempre envie cabeçalhos Retry-After e de cota para que os clientes possam se comportar.
• Limite a taxa por chave/usuário em vez de por IP simples quando possível, para evitar punir redes compartilhadas.

Exemplo de resposta

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

{"error":"rate_limited","retry_after":30}

Perguntas frequentes