HTTP 429 Too Many Requests: espere e tente de novo do jeito certo
HTTP 429 Too Many Requests
HTTP 429 Too Many Requests: Retry-After e backoff | We.Inc
O que o status 429 significa, como ler o Retry-After e código de retry com backoff exponencial e jitter. Planeje o seu próprio calendário de novas tentativas com a calculadora.
Uma resposta 429 significa que o servidor está aplicando rate limit em você: este cliente enviou mais requisições em uma janela de tempo do que ele permite. Pare de enviar por um tempo. Se a resposta trouxer um cabeçalho Retry-After, espere esse tempo; se não, tente de novo com backoff exponencial mais jitter aleatório, para que muitos clientes não tentem de novo todos ao mesmo tempo.
Como ler uma resposta 429
Parte
O que ela diz
O que o seu cliente deve fazer
Status 429
Requisições demais em um dado intervalo de tempo
Pausar este cliente, sem bombardear o servidor
Retry-After: 120
Espere 120 segundos (forma de atraso em segundos)
Aguardar pelo menos esse tempo
Retry-After: Wed, 21 Oct 2026 07:28:00 GMT
Espere até esse horário (forma HTTP-date)
Subtrair o horário atual e então aguardar
Sem Retry-After
O servidor não deu nenhuma pista
Recuar de forma exponencial com jitter
Cache
Um 429 não pode ser guardado por um cache
Nunca servir mais tarde um 429 guardado
Defina o primeiro atraso, o teto e quantas novas tentativas você permite, e escolha um estilo de jitter. A calculadora lista a faixa de espera de cada tentativa e o total no pior caso, para você ver se o seu cliente desiste antes de a janela do servidor reiniciar.
Informe o atraso base em milissegundos, o atraso usado antes da primeira nova tentativa.
Informe o teto, o máximo que uma única espera pode durar.
Escolha quantas novas tentativas permitir e um estilo de jitter.
Leia as faixas por tentativa e o total, depois copie o código correspondente abaixo.
Respeite o Retry-After acima do seu próprio calendário sempre que o servidor o enviar. Ele sabe quando a janela reinicia, e você não.
Só repita requisições que podem ser repetidas com segurança. Um POST de pagamento repetido sem chave de idempotência pode cobrar duas vezes.
Limite o número de novas tentativas além do atraso, e mostre um erro claro quando elas acabarem.
Quando o servidor é seu, devolva 429 com Retry-After em vez de descartar ou atrasar requisições em silêncio, para que clientes bem-comportados possam se adaptar.
Perguntas frequentes
429 é um erro do cliente ou do servidor?
Está na classe 4xx, então descreve o comportamento do cliente: requisições demais. Nada está quebrado no servidor. A solução é enviar menos requisições ou espalhá-las no tempo.
O que o Retry-After contém?
Ou um número de segundos para esperar, como 120, ou uma data HTTP depois da qual você pode tentar de novo. O seu cliente deve tratar as duas formas.
Por que adicionar jitter ao backoff exponencial?
Sem jitter, todo cliente que falhou no mesmo instante tenta de novo no mesmo instante, o que recria o pico. Uma espera aleatória dentro de cada janela espalha as novas tentativas.
Por que o rate limit do meu nginx devolve 503 em vez de 429?
O módulo limit_req rejeita com 503, a menos que você mude isso. Adicione limit_req_status 429; ao lado da sua linha limit_req para que os clientes vejam o código mais preciso.
Uma CDN pode guardar uma resposta 429 em cache?
Não pode. A RFC 6585 diz que respostas com o código de status 429 não podem ser guardadas por um cache, então cada cliente recebe uma resposta nova quando o limite é liberado.
Quem envia 429 e por quê
APIs, formulários de login e endpoints de busca contam requisições por usuário, por chave ou por endereço IP e recusam as excedentes. A especificação deixa a contagem a critério do servidor, então uma API pode limitar por minuto e outra por dia.
A resposta deve explicar o limite no corpo, e pode acrescentar Retry-After para dizer quanto tempo esperar.
Os três estilos de backoff da calculadora
O backoff exponencial simples dobra a espera a cada vez até o teto: min(cap, base * 2^attempt). O full jitter escolhe uma espera aleatória entre zero e esse número. O equal jitter mantém metade dele e torna a outra metade aleatória, o que garante uma pausa mínima.
O full jitter distribui melhor a carga, e por isso é um padrão sensato. O equal jitter serve para clientes que nunca podem tentar de novo imediatamente.
Código de cliente que respeita o 429
fetch com Retry-After e full jitter
Lê as duas formas de Retry-After, usa full jitter como alternativa e para depois de um número fixo de novas tentativas.
Enviando 429 do seu próprio servidor
nginx: limite por IP e resposta com 429
limit_req rejeita com 503 por padrão; limit_req_status troca para 429.
Como a resposta fica
Um corpo curto explicando o limite e um Retry-After em segundos.
Calculadora de calendário de novas tentativas
Atraso base (ms)
Teto por espera (ms)
Novas tentativas
Estilo de jitter
Full jitter
Equal jitter
Sem jitter
Espera antes de cada nova tentativa
Tentativa
Espera mais curta
Espera mais longa
Pior caso antes de desistir: {v}
Use números inteiros maiores que zero, com o teto pelo menos igual à base.