HTTP 429 e Backoff Exponencial
Nesta página
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