429: como repetir sem piorar

Sua integração funciona há três meses. Numa terça-feira, começa a receber 429. Você adiciona uma retentativa. No dia seguinte, o 429 virou constante.

Isso não é azar: é o comportamento esperado de retentativa mal feita.

O que 429 quer dizer

Você passou do número de requisições permitido numa janela de tempo. Não é erro do seu código nem falha do servidor — é um pedido para diminuir o ritmo.

Duas coisas seguem dele. A primeira: repetir imediatamente não ajuda, porque a janela não passou. A segunda: repetir imediatamente atrapalha, porque consome mais da cota e empurra a recuperação para longe.

Por que a retentativa ingênua piora

for (let i = 0; i < 3; i++) {
  const r = await chamar();
  if (r.ok) return r;
}

Uma requisição que falhou virou três. Sob carga, quando muitos clientes recebem 429 ao mesmo tempo, todos repetem juntos — e voltam a bater juntos no mesmo instante. O sistema entra num ciclo em que a própria retentativa mantém o limite estourado.

Como fazer certo

Espere mais a cada tentativa. Dobrar o intervalo dá tempo de a janela virar: um segundo, dois, quatro, oito.

Some um valor aleatório. Sem isso, todos os clientes repetem no mesmo milissegundo e a coordenação acidental recria o pico. Um sorteio pequeno espalha as tentativas.

const espera = base * 2 ** tentativa + Math.random() * 1000;

Obedeça o Retry-After. Quando o servidor manda esse cabeçalho, ele está dizendo exatamente quanto esperar. Respeitar é sempre melhor que adivinhar.

Tenha um teto. Cinco tentativas bastam. Depois disso, falhe e registre. Repetir para sempre transforma uma indisponibilidade curta numa fila que nunca drena.

O que nunca deve ser repetido

Aqui mora o bug caro.

Repetir uma leitura é inofensivo. Repetir uma criação pode gerar duas — e no caso de um pedido, dois débitos no saldo.

A regra: só repita automaticamente o que é seguro repetir. Leitura, sim. Criação, só com proteção.

A proteção é uma chave de idempotência: um identificador que você gera antes da primeira tentativa e reenvia em todas. O servidor reconhece a repetição e devolve o mesmo resultado em vez de criar outro.

Sem esse recurso, a alternativa é conferir antes de recriar: consulte se o pedido daquele seu identificador interno já existe.

Erros que também não devem ser repetidos

Nem toda falha melhora com insistência:

Código	Repetir?
400, 422	Não. O corpo está errado; repetir manda o mesmo erro.
401, 403	Não. Credencial inválida não melhora sozinha.
404	Não.
409	Não sem pensar. Costuma indicar duplicidade.
429	Sim, com espera crescente.
500, 502, 503, 504	Sim, com espera crescente.
Tempo esgotado de conexão	Sim para leitura. Para criação, só com idempotência.

O caso perigoso é o tempo esgotado numa criação: você não sabe se o servidor recebeu. Talvez o pedido exista e a resposta é que se perdeu.

Evitar o limite é melhor que reagir a ele

Antes de aperfeiçoar a retentativa, veja se dá para fazer menos requisições:

• Guarde o que muda devagar. Lista de países e serviços não precisa ser buscada a cada pedido.
• Troque consulta por aviso. A maior fonte de requisição inútil costuma ser laço de espera. Webhook zera isso.
• Enfileire picos. Se o seu processo cria trezentos pedidos de uma vez, uma fila com concorrência limitada espalha no tempo e nunca encosta no limite.

Registre o suficiente para investigar

Quando o 429 aparecer, você vai querer saber: qual rota, quantas tentativas, qual espera, e se havia Retry-After. Registro que só diz "falhou ao criar pedido" não permite concluir nada.

E não repita em silêncio. Três tentativas invisíveis viram três segundos de latência que ninguém consegue explicar depois.

Na API de números virtuais, o teto é de 120 requisições por minuto por chave e 20 pedidos por minuto por conta, e o 429 vem com Retry-After.