Ir para o conteúdo principal
Português— Escolher um idioma
Menu

HTTP 429 e Backoff Exponencial

Aula 3 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. Gestão de Excedentes de Limite
  2. O Que Não Fazer
  3. Backoff Exponencial
  4. Escalabilidade: Regule Antes de Falhar
  5. Trate o 429 como uma Métrica
  6. Pontos-chave

Gestão de Excedentes de Limite

Assim que a sua aplicação atinge os limites de RPM (requisições por minuto) ou TPM (tokens por minuto), a API Grok responde com um código de estado HTTP 429 (Too Many Requests). Leia este código pelo que ele é: não uma falha do serviço, mas um sinal de controlo de fluxo. A API está a dizer «abrande», não «está avariado». A diferença entre uma integração robusta e uma frágil reside na forma como o seu código interpreta esta distinção. Um erro 429 mal gerido nunca fica isolado: propaga-se pela fila de espera, afeta os serviços chamadores e termina num incidente visível para o utilizador final.

O Que Não Fazer

A reação instintiva quando um pedido falha é reenviá-lo imediatamente. Esta é exatamente a decisão errada. Já excedeu a sua quota; ao reenviar de imediato, gasta uma chamada adicional que também irá falhar e prolonga o período de bloqueio em vez de o encurtar. Uma tentativa de repetição infinita agrava a situação, ocupando threads inutilmente. Por outro lado, tratar o 429 como um erro permanente e desistir priva o seu utilizador de um resultado que teria chegado alguns segundos depois. A abordagem correta situa-se entre estes dois extremos: tente novamente, mas espere, e aumente o tempo de espera a cada tentativa.

Backoff Exponencial

O princípio consiste em duplicar o atraso após cada tentativa falhada, adicionando uma variação aleatória designada por jitter.

import time
import random

def call_with_retry(request, max_retries=5):
    for attempt in range(max_retries):
        response = send_request(request)

        if response.status_code != 429:
            return response

        base_delay = 2 ** attempt  # 1, 2, 4, 8, 16 seconds
        jitter = random.uniform(0, base_delay * 0.5)
        delay = base_delay + jitter

        time.sleep(delay)

    raise Exception("Retry limit reached")

O jitter merece atenção, pois é frequentemente a linha de código eliminada sob o pretexto de complicar desnecessariamente o código. Imagine trinta instâncias do seu serviço a receberem um 429 no mesmo segundo. Sem jitter, todas calculam o mesmo atraso e tentam novamente exatamente no mesmo momento: reproduziu o pico de carga identicamente, um segundo depois, depois dois, depois quatro. Este é o fenómeno do thundering herd (manada em pânico). A aleatorização distribui as tentativas ao longo do tempo e quebra esta sincronização involuntária. Note também que o atraso base começa em um segundo: nunca desça abaixo deste valor para a primeira tentativa.

Escalabilidade: Regule Antes de Falhar

Numa aplicação de alto volume, reagir aos erros 429 já não é suficiente; é preferível evitá-los. Um limitador de taxa do lado do cliente (client-side rate limiter) restringe o número de chamadas simultâneas e impõe um espaçamento mínimo entre envios, garantindo que a carga de saída se mantém abaixo do teto, em vez de o testar constantemente.

import asyncio
from asyncio import Semaphore

# Limit to 25 requests/second (margin under the allowed 30 req/s)
semaphore = Semaphore(25)

async def limited_request(payload):
    async with semaphore:
        response = await send_request_async(payload)
        await asyncio.sleep(1.0 / 25)  # minimum spacing
        return response

Observe a margem deliberada: 25 pedidos por segundo em vez dos 30 permitidos. Esta reserva absorve irregularidades de rede e picos de tráfego sem nunca atingir o limite máximo.

O disjuntor (circuit breaker) completa a configuração, interrompendo as chamadas quando as falhas se acumulam. Enquanto fechado, os pedidos passam normalmente. Após um número definido de falhas consecutivas, ele abre e recusa localmente todos os pedidos durante um período configurado: deixa de sobrecarregar uma API que o está a rejeitar e as suas threads permanecem disponíveis para o resto da aplicação. Quando o tempo de espera expira, passa para o estado semi-aberto (half-open) e permite a passagem de um único pedido de teste; se este for bem-sucedido, o tráfego normal retoma, caso contrário, o contador é reiniciado. Este mecanismo protege o seu serviço tanto quanto a API no outro extremo.

Trate o 429 como uma Métrica

Um último reflexo, frequentemente ausente nas integrações: instrumente a taxa de erros 429. Este valor não mede a qualidade do seu código de repetição; mede a adequação entre o seu plano de subscrição e o seu tráfego real. Uma curva que sobe semana após semana sinaliza um dimensionamento insuficiente muito antes de os utilizadores se queixarem, dando-lhe tempo para agir com calma — distribuir a carga, orçamentar uma atualização de plano — em vez de improvisar numa sexta-feira à noite.

Pontos-chave

  • O código HTTP 429 sinaliza um excedente dos limites de RPM ou TPM
  • O backoff exponencial com jitter é a estratégia recomendada pela xAI
  • Em produção, complemente o backoff com um limitador de taxa do lado do cliente e um disjuntor (circuit breaker)
  • Nunca tente novamente imediatamente: espere pelo menos 1 segundo antes da primeira repetição
  • Monitore a taxa de erros 429 nas suas métricas como um indicador de dimensionamento insuficiente