Erro 429 (rate limit) na API da OpenAI: por que acontece e como resolver

Fala programador(a), beleza? Você monta a integração, testa local, tá tudo lindo… aí a produção sobe e vem o 429 Too Many Requests bem no meio da chamada.

O detalhe cruel é que o mesmo código 429 esconde dois problemas completamente diferentes. Um é tráfego demais (você mandou requisição ou token acima do limite por minuto). O outro é billing (seu saldo ou sua cota de faturamento acabou). E aqui tá a pegadinha: a solução de um NÃO resolve o outro. Se você tratar tudo como "vou retentar depois", pode ficar batendo a cabeça num problema que é de cartão de crédito, não de código. Então bora separar as duas causas primeiro, depois resolver cada uma.

Causa 1: rate_limit_exceeded (tráfego alto, RPM/TPM/RPD/TPD)

Esse é o 429 clássico de pressão de tráfego.

O sintoma: a resposta vem com código rate_limit_exceeded e traz os headers de rate limit junto. Se liga neles: x-ratelimit-remaining-requests e x-ratelimit-remaining-tokens mostram o que ainda sobra do seu limite, e o Retry-After diz em quantos segundos você pode tentar de novo.

A causa: a OpenAI mede seu uso em quatro dimensões ao mesmo tempo: requisições por minuto (RPM), tokens por minuto (TPM), requisições por dia (RPD) e tokens por dia (TPD). E aqui vai o ponto que muita gente não sacou: basta estourar UMA dessas quatro pra levar 429. Ou seja, você pode estar tranquilo no RPM e mesmo assim tomar bloqueio porque encheu o TPM com respostas gigantes.

A solução: backoff exponencial com jitter. A ideia é simples: quando toma 429, você espera um intervalo curto antes de retentar, e aumenta esse tempo a cada nova falha, até um número máximo de tentativas. O jitter é uma variação aleatória nessa espera pra suas requisições não baterem todas no mesmo instante.

E o erro que quase todo mundo comete: reenviar na hora. Não funciona. A requisição que falhou ainda conta pro seu limite por minuto, então retentar imediatamente só afunda mais o buraco. Sempre respeite o Retry-After: ele te dá o tempo exato de espera, não precisa chutar.

Como prevenir: faz throttle no seu lado (segura o ritmo de disparo pra não encostar no teto) e reduz o consumo por requisição. Ajustar o max_tokens (e o best_of) pro menor valor que atende seu caso corta o gasto de tokens por minuto, que é justo o que enche o TPM.

Causa 2: insufficient_quota (saldo ou cota de faturamento esgotado)

Esse aqui é traiçoeiro porque vem com o MESMO 429, só que a raiz não tem nada a ver com tráfego.

O sintoma: a mensagem diz insufficient_quota, e o mais revelador: acontece mesmo quando você tá mandando pouquíssima requisição. Uma chamada solta, sem volume nenhum, e mesmo assim 429? Aí acende a luz.

A causa: é billing. Seu saldo acabou, a cota de faturamento chegou no fim, ou o plano tá sem crédito disponível. Não é o servidor da OpenAI dizendo "calma que tá muito rápido", é o financeiro dizendo "não tem crédito aqui".

A solução: recarregar saldo e conferir seu plano de faturamento na conta. Ponto. E deixa eu ser bem direto sobre uma coisa: backoff exponencial NÃO resolve este caso. Você pode botar 50 tentativas com espera crescente que não adianta nada, porque o problema não é tempo, é crédito. Retentar aqui é só perder tempo.

Como prevenir: configura alertas de uso na sua conta pra ser avisado antes do saldo secar. Assim você recarrega antes do 429 estourar em produção, e não depois.

Como resolver o 429 de rate limit na prática

Beleza, identificou que o seu caso é o de tráfego (Causa 1)? Então vamos ao passo a passo. Se o seu for insufficient_quota, pula direto pro billing, porque nada abaixo vai te ajudar.

1. Identifique a causa pela mensagem e pelos headers. Antes de tocar em qualquer linha de código, leia a resposta do erro. Olha o campo da mensagem (rate_limit_exceeded ou insufficient_quota) e os headers Retry-After e x-ratelimit-remaining-requests / x-ratelimit-remaining-tokens.

O erro comum deste passo: sair mexendo no código sem ler a mensagem. Se for insufficient_quota, você vai construir um retry lindo que nunca vai funcionar.

1. Ative e ajuste o retry do SDK. O SDK oficial de Python já retenta o 429 sozinho por padrão, 2 vezes. Se seu caso pede mais fôlego, dá pra subir esse teto:

   from openai import OpenAI

   client = OpenAI(max_retries=5)

O erro comum deste passo: achar que o SDK não retenta e sair reinventando a roda. Ele já retenta; muitas vezes é só ajustar o max_retries.

1. Implemente backoff exponencial com jitter no seu código próprio. Se você não usa o SDK ou quer controle fino, faça na mão: espera curta que cresce a cada falha, com uma pitada de aleatoriedade.

   import time, random

   def chamar_com_backoff(fn, max_tentativas=5):
       for tentativa in range(max_tentativas):
           try:
               return fn()
           except Exception:
               if tentativa == max_tentativas - 1:
                   raise
               espera = (2 ** tentativa) + random.uniform(0, 1)
               time.sleep(espera)

O erro comum deste passo: esquecer o jitter (aquele random.uniform). Sem ele, várias requisições retentam no mesmo segundo exato e batem no limite de novo, todas juntas.

1. Reduza o consumo por requisição. Define o max_tokens no mínimo necessário pro tamanho de resposta que você espera. Menos tokens por chamada = menos pressão no TPM = menos 429.

   resposta = client.chat.completions.create(
       model="gpt-4o",
       messages=mensagens,
       max_tokens=300,  # o suficiente pra resposta esperada, nem mais
   )

O erro comum deste passo: deixar o max_tokens alto "por segurança". Isso reserva orçamento de token que você nem vai usar e te aproxima do limite por minuto à toa.

Tiers de uso: por que seu limite é o que é (e como aumentá-lo)

Uma pergunta que vem logo: "beleza, mas por que MEU limite é tão baixo?". A resposta é o tier da sua conta.

Os limites de taxa dependem do tier de uso, e ele sobe automaticamente conforme duas coisas: o gasto acumulado e a idade da conta. Funciona mais ou menos assim: o Tier 1 é liberado quando você faz o primeiro pagamento de pelo menos US$5. O Tier 2 já exige duas condições ao mesmo tempo: US$50 em pagamentos acumulados E pelo menos 7 dias desde o primeiro pagamento. As duas juntas, não uma ou outra.

E tem um detalhe importante que confunde muita gente: o que conta é o gasto acumulado de todos os tempos (all-time), não o saldo que você tem agora. Ou seja, se você já pagou US$50 no total ao longo do uso, sua conta vai pro Tier 2 mesmo que o saldo atual esteja zerado. É histórico, não é o que sobra na conta hoje.

Quer conferir em que tier você está e quais são seus limites de verdade? Dá pra ver tudo na área de configurações da plataforma, na seção Limits. A página oficial de referência é a platform.openai.com/docs/guides/rate-limits. Vale abrir e olhar os números da SUA conta antes de assumir qualquer coisa.

Conclusão

Recapitulando o que importa: o erro 429 API OpenAI é sempre um diagnóstico de duas frentes. Ou é rate_limit_exceeded (tráfego alto, você estourou uma das dimensões RPM/TPM/RPD/TPD, e a saída é backoff com jitter respeitando o Retry-After), ou é insufficient_quota (billing no fim, e a saída é recarregar saldo). Tratar um com a solução do outro é perder tempo.

Seu próximo passo concreto é sempre o mesmo: antes de mexer no código, leia a mensagem do erro e os headers x-ratelimit. Eles te dizem em segundos qual dos dois problemas você tem. E pra saber o teto real da sua conta, é só conferir a seção Limits nas configurações da plataforma.

E por hoje é isso, até o próximo post! 🙂