Os três tipos de 429
HTTP 429 é o status padrão "muitas requisições". Aqui cobre três situações, e o corpo JSON do erro indica qual você está enfrentando.
| Código de erro | O que significa | Correção típica |
|---|---|---|
rate_limited | Muitas requisições por minuto | Reduza a velocidade, distribua requisições ao longo do minuto |
concurrency | Muitas requisições rodando ao mesmo tempo | Reduza a paralelização, aguarde os slots liberarem |
Sobrecarga, com Retry-After: 5 | Carga temporária no serviço, não é culpa sua | Aguarde o número de segundos no cabeçalho, depois tente novamente |
Leia o código primeiro, pois uma correção para uma causa não serve para outra. Reduzir pela metade suas requisições por minuto não ajuda se o problema real são 20 workers disparando ao mesmo tempo.
Conheça seus limites
Os limites dependem do tipo de chave:
- Chave completa: 8 requisições concorrentes e 300 requisições por minuto.
- Chave de teste: 2 requisições simultâneas e 60 requisições por minuto.
Cada resposta inclui X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency, para que seu cliente possa ler o limite máximo em vez de codificá-lo fixamente. A chave de teste é o principal responsável pelos problemas para novos usuários: um script que funciona bem com 1 requisição por vez começa a falhar quando você adiciona um pool de threads com 4. O período de teste é destinado à avaliação, e uma chave completa é fornecida com qualquer recarga a partir de $20 (veja a página de preços para valores e bônus).
Os números acima são por chave. Se uma chave é compartilhada por um app web, um job cron e o notebook de um colega, todos usam o mesmo pool, e os 429s parecerão aleatórios até você somar as três cargas de trabalho.
Por que streaming aumenta erros de concorrência
Uma requisição normal ocupa um slot de concorrência por um ou dois segundos. Uma requisição de streaming (stream: true) ocupa até o último token chegar e o streaming fechar. Uma resposta longa pode manter um slot ocupado por dezenas de segundos, então 8 slots desaparecem rápido num app de chat com vários usuários ativos.
Dois erros causam a maioria dos problemas aqui. O primeiro é abandonar um streaming sem fechá-lo: se o cliente para de ler mas deixa a conexão aberta, o slot fica ocupado até o fim da conexão. Sempre feche a resposta num bloco finally, ou use o gerenciador de contexto do SDK. O segundo é retentar um streaming abrindo um segundo enquanto o primeiro ainda está vivo, o que dobra o uso de slots exatamente quando você está sem slots.
Se seu app precisa de mais streaming longo simultâneo do que sua chave permite, coloque novas conversas em fila do seu lado e mostre um estado de espera curto. Isso é melhor do que deixar usuários verem erros brutos.
Código de retentativa em Python com backoff
O padrão é simples: capture o 429, leia o código, espere, tente novamente com atraso crescente e alguma aleatoriedade, e desista após algumas tentativas. Esta versão usa o pacote oficial openai contra a URL base do serviço:
import random
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
max_retries=0, # we handle retries ourselves
)
def chat(messages, attempts=5):
for i in range(attempts):
try:
r = client.chat.completions.create(
model="uncensored",
messages=messages,
)
return r.choices[0].message.content
except RateLimitError as e:
headers = e.response.headers
wait = float(headers.get("Retry-After", 0))
if not wait:
wait = min(30, 2 ** i) # 1, 2, 4, 8, 16 seconds
wait += random.uniform(0, 1) # jitter
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(chat([{"role": "user", "content": "Reply with the word ok."}]))
Quando o cabeçalho está presente, use-o como espera mínima. Quando ausente, o atraso exponencial funciona para rate_limited porque a janela por minuto avança. O jitter evita que muitos workers retentem ao mesmo instante.
Limite chamadas paralelas para evitar 429
Retries tratam o sintoma. Um semáforo evita a maioria deles não enviando mais do que sua contagem de slots. Defina-o um pouco abaixo do limite para que uma tentativa ou uma solicitação perdida ainda tenha espaço:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6) # full key allows 8; use 1 on a trial key
async def ask(prompt):
async with sem:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(50)]
results = await asyncio.gather(*(ask(p) for p in prompts))
print(len(results))
asyncio.run(main())
Para o limite por minuto, 300 requisições por minuto são 5 por segundo em média. Se você agrupa milhares de jobs curtos, adicione um pequeno sleep ou um token bucket antes do semáforo. Como o SDK também retenta por padrão, defina max_retries explicitamente para que sua lógica e a do SDK não empilhem e multipliquem as esperas.
Reproduza e inspecione um 429 com curl
Antes de mudar o código, veja a resposta bruta. Adicione -i ao curl para imprimir os cabeçalhos, e dispare algumas requisições em paralelo para provocar o erro de propósito:
for i in 1 2 3 4; do
curl -i -s https://api.onekeyllmapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait
Em uma chave de teste, que permite 2 requisições ao mesmo tempo, a terceira e quarta chamadas devem retornar status 429 e código de erro concurrency. Com uma chave completa você precisaria de mais de 8 ao mesmo tempo. Observe três coisas em cada resposta: a linha de status, o cabeçalho Retry-After se houver, e o campo error.code no corpo JSON. Esse pequeno experimento diz mais do que uma hora de adivinhação, e dá um caso reproduzível para mostrar ao suporte se algo parecer errado.
Projete para lidar com isso, não ao redor
Trate um 429 como um evento normal, como um timeout. Coloque chamadas de modelo atrás de uma função, registre cada nova tentativa com seu motivo, e exponha um contador para notar quando as tentativas aumentam. Uma taxa de novas tentativas crescente é um sinal precoce de que seu tráfego superou os limites de uma única chave, muito antes dos usuários reclamarem. Para produtos de chat, uma pequena fila em memória por usuário impede que uma conta ocupada leve todos os 8 slots dos outros usuários.
Uma lista de verificação rápida de depuração
- Registre o corpo completo do erro e o cabeçalho
X-Request-Idpara cada 429. O campo code separarate_limiteddeconcurrency. - Verifique se sua chave é uma chave de teste. Se sim, espere 2 requisições simultâneas e 60 por minuto.
- Conte todos os programas que usam a chave, não apenas o que falhou.
- Procure streams não fechados, e loops que fazem retry instantaneamente sem atraso. Um loop de retry instantâneo transforma um 429 em cem.
- Confirme o saldo com
X-Balance-USDouGET /v1/balance. Um saldo vazio é um problema diferente de um 429, mas verificar leva segundos.
Requisições falhas não são cobradas, então tentar novamente não custa tokens para as tentativas rejeitadas. Para a lista completa de códigos de status e cabeçalhos, consulte a documentação. Se você precisar de uma chave com limites mais altos do que uma chave de teste, obtenha uma chave de API e recarregue.
