Erro 429 Too Many Requests

A RFC 6585, seção 4, define o 429 e deixa a política de propósito nas mãos do servidor: ela não diz como identificar o usuário nem como contar os pedidos. O limite pode ser por IP, por chave de API, por conta, por endpoint ou compartilhado por um cluster inteiro, e o mesmo cliente pode estar sujeito a vários ao mesmo tempo. A RFC sugere Retry-After e um corpo explicando o limite, e proíbe caches de guardar a resposta.

Ainda não existe cabeçalho padrão para a cota em si. Muitas APIs mandam X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, e a IETF está padronizando os campos RateLimit e RateLimit-Policy num rascunho (draft-ietf-httpapi-ratelimit-headers). Ler esses cabeçalhos permite ao cliente desacelerar antes de bater no limite, não depois.

Nem todo limitador responde 429. O limit_req do nginx recusa com 503, a menos que você configure limit_req_status 429, e alguns WAFs e CDNs usam 403 ou páginas de desafio próprias para a mesma situação.

Se você está visitando o site

• Atualizar a página, tentar o login ou clicar em "reenviar código" muitas vezes num curto período.
• IP compartilhado (escritório, faculdade, NAT da operadora móvel, saída de VPN) em que outras pessoas gastam o limite por IP.
• Uma extensão do navegador, gerenciador de downloads ou scraper acessando o site em segundo plano.

Se você administra o servidor

• Um cliente de API dispara pedidos num loop apertado ou com concorrência ilimitada, por exemplo Promise.all em milhares de itens.
• Tentativas sem espera: cada falha dispara nova tentativa na hora, o que multiplica a taxa justamente quando o servidor está pedindo calma.
• Vários workers ou instâncias serverless dividem a mesma chave de API, e a taxa somada passa do limite que cada um respeita sozinho.
• O seu próprio limitador usa o endereço do proxy em vez do IP do cliente, então todos os visitantes atrás do load balancer caem no mesmo balde.

Se você está visitando o site

• Pare de tentar e espere. Muitos limites zeram em um minuto; limites de login e de código por SMS podem durar de 15 minutos a uma hora.
• Se estiver numa VPN ou rede compartilhada, troque de rede ou desligue a VPN.
• Desative extensões que pré-carregam ou raspam páginas e tente de novo.

Se você administra o servidor

• Respeite o Retry-After à risca quando ele vier; o valor é um número de segundos ou uma data HTTP.
• Sem Retry-After, espere de forma exponencial com jitter: um tempo aleatório entre 0 e min(teto, base x 2^tentativa), para uma frota de clientes não tentar de novo toda ao mesmo tempo.
• Limite a concorrência (uma fila ou um pool de N pedidos em andamento) e acompanhe o X-RateLimit-Remaining para desacelerar antes de zerar.
• Atrás de proxy, identifique o cliente pelo IP real (Express: app.set("trust proxy", 1)) e responda 429 com Retry-After, não 503 nem 403.

O express-rate-limit responde 429 por padrão. No código do seu cliente, a linha de curl no final mostra o comportamento a copiar: tentar de novo no 429, esperar o que o Retry-After mandar e dobrar a espera quando ele não vier.

import { rateLimit } from 'express-rate-limit';

// Over the limit, the middleware answers 429 with Retry-After
app.use('/api', rateLimit({
  windowMs: 60 * 1000,
  limit: 100,                 // requests per client per window
  standardHeaders: 'draft-8', // RateLimit + RateLimit-Policy headers
  legacyHeaders: false
}));

// app/api/search/route.ts
export async function GET() {
  return Response.json(
    { error: 'Rate limit exceeded, retry in 60 seconds' },
    { status: 429, headers: { 'Retry-After': '60' } }
  );
}

mux.HandleFunc("GET /api/search", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Retry-After", "60")
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusTooManyRequests) // 429
	w.Write([]byte(`{"error":"Rate limit exceeded, retry in 60 seconds"}`))
})

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/api/search")
def search():
    raise HTTPException(status_code=429, detail="Rate limit exceeded, retry in 60 seconds", headers={"Retry-After": "60"})

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

server {
  location /api/ {
    limit_req zone=api burst=20 nodelay;
    limit_req_status 429;  # the default is 503
    proxy_pass http://app;
  }
}

# curl treats 429 as transient: it retries with doubling delays
# and honors Retry-After (curl 7.66.0 and later)
curl --retry 5 --retry-max-time 300 https://api.example.com/search?q=http

429 vs 503

O 503 diz que o serviço inteiro está sobrecarregado ou fora do ar para todos; o 429 diz que este cliente passou da própria cota enquanto os outros são atendidos normalmente.

429 vs 403

O 403 é uma recusa que esperar não resolve; o 429 é temporário e passa quando a janela do limite zera.

429 vs 402

Algumas APIs respondem 402 quando a cota mensal paga acaba; o 429 é sobre ritmo de pedidos no curto prazo, e esperar resolve.

Quanto tempo esperar depois de um erro 429?

Olhe o cabeçalho Retry-After: ele traz os segundos de espera ou uma data. Sem ele, depende do serviço; muitas APIs zeram o limite a cada minuto, enquanto limites de login e de código de verificação costumam durar de 15 a 60 minutos.

Erro 429 Too Many Requests é banimento?

Não, ele é temporário por definição e acaba quando a janela zera. Se não passa nem depois de esperar, pode ser um bloqueio mais longo de firewall, que normalmente aparece como 403.

Como um cliente de API deve tratar o 429?

Pare de enviar, espere o tempo do Retry-After e tente de novo. Se não houver Retry-After, use espera exponencial com jitter e um número máximo de tentativas, e diminua a concorrência para não bater no mesmo limite logo em seguida.

Por que aparece erro 429 no ChatGPT, Instagram ou outros sites grandes?

Serviços grandes aplicam limites por conta e por IP em mensagens, logins e ações. Atingir um deles, ou dividir o IP com muita gente por VPN ou rede da operadora, gera 429 ou a mensagem "muitas solicitações" até o limite zerar.

Minha API deve responder 429 ou 503 ao limitar a taxa?

Responda 429 com Retry-After quando um cliente específico passou da cota. Use 503 só quando o serviço inteiro não consegue aceitar trabalho. O limit_req do nginx usa 503 por padrão, então configure limit_req_status 429.