HTTP 429: interpretar Retry-After e repetir pedidos com segurança

Descubra quem devolveu a resposta

Registe hora, endereço do recurso, método, estado, identificador do pedido e cabeçalhos de espera; exclua credenciais e dados pessoais. Distinga API, proxy e CDN. Uma página de erro com uma marca não prova a origem.

A quota pode ser por IP, utilizador, aplicação ou recurso. Limites por minuto, concorrência e quota diária pedem soluções diferentes: abrandar alguns segundos não repõe uma quota diária esgotada.

• Aumentaram os trabalhos ou as repetições?
• Outros serviços, separadores ou chaves partilham a conta?
• O limite mede pedidos, pedidos ativos, tokens ou outro recurso?
• A recuperação cabe no prazo do utilizador?

Interprete as unidades de Retry-After

O valor pode ser um inteiro não negativo em segundos ou uma data HTTP. O valor 12 significa 12 segundos, não milissegundos. Datas exigem um relógio fiável; uma data passada não deve causar repetições contínuas.

Respeite a espera mínima do servidor e acrescente dispersão aleatória. Se ultrapassar o prazo do trabalho, pare ou reagende. Não reduza a espera exigida para caber num máximo local inferior.

Calcule o orçamento da fila inteira

Se toda a conta dispõe de 120 pedidos por minuto, 600 precisam de pelo menos cinco minutos sem outro tráfego. Enviá-los em dez segundos e descansar depois continua a ser uma rajada.

Um alvo de 90 por minuto equivale a 1.5 por segundo, cerca de um início a cada 667 milissegundos. Os 600 pedidos exigem 400 segundos, antes de latência e repetições. Com respostas de 2 segundos, a média é 1.5 × 2 = 3 pedidos em curso. Um semáforo limita os ativos; um regulador partilhado limita os inícios. As repetições consomem o mesmo orçamento.

Example workload assumptions:
Account allowance: 120 requests/minute
Operating target: 90 requests/minute = 1.5 requests/second
600 requests / 1.5 requests/second = 400 seconds
Average concurrency at 2 seconds/response: 1.5 × 2 = 3

Use espera progressiva com dispersão

Sem uma espera válida, pode aumentar a janela para um, dois, quatro e oito segundos e sortear o intervalo real. A dispersão evita que todos os processos retomem juntos.

A função apenas calcula a demora. Quem a chama deve impor prazo, limite de tentativas, cancelamento e segurança da repetição. Num navegador, CORS pode exigir que o servidor exponha Retry-After.

function retryDelayMs(retryAfter, attempt, nowMs = Date.now()) {
  const text = String(retryAfter ?? "").trim();
  if (/^\d+$/.test(text)) {
    const milliseconds = Number(text) * 1000;
    return Number.isSafeInteger(milliseconds) ? milliseconds : Infinity;
  }
  if (/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(text)) {
    const dateMs = Date.parse(text);
    if (Number.isFinite(dateMs)) return Math.max(0, dateMs - nowMs);
  }
  const windowMs = Math.min(8000, 1000 * 2 ** attempt);
  return Math.floor(Math.random() * windowMs);
}
// Example policy: at most 4 retries and a 30-second total deadline.
// If the required wait exceeds the remaining deadline, stop.

Não duplique efeitos da operação

Ler dados é diferente de criar um pagamento. Verifique a idempotência e se o primeiro pedido já produziu um efeito. Reutilize a chave da mesma operação lógica; mudar de chave a cada tentativa pode criar duplicados.

O SDK pode já repetir pedidos. Uma camada exterior multiplica as tentativas de rede. Imponha um limite conjunto e, em ações interativas, apresente a opção de tentar mais tarde em vez de uma espera interminável.

• Defina um prazo total e cancele a fila pendente.
• Partilhe limites de concorrência e ritmo.
• Liberte recursos da resposta antes da espera.
• Pare perante quota esgotada ou falha permanente.
• Registe tentativas e resultado final.

Valide com um lote pequeno

Comece com vinte leituras e conte pedidos iniciais, repetições, sucessos e falhas finais. Verifique espaçamento e pedidos ativos. Simule 429 e Retry-After sem sobrecarregar um serviço real.

Planeie com as calculadoras de pedidos por segundo e concorrência e confronte o resultado com as regras reais. Se persistir o limite, investigue outros consumidores e a dimensão da quota antes de aumentar a espera.