PT ▾
Obter chave de API

Erro 429 na API LLM: causas e como resolver

O erro 429 na API LLM significa que o servidor está recusando uma requisição por enquanto, não permanentemente. Nesta API, há três causas distintas, cada uma exigindo uma correção ligeiramente diferente.

Atualizado

Pacotes de luz fazendo fila em um portão com oito faixas, ilustrando limites de taxa da API

Pontos principais

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 erroO que significaCorreção típica
rate_limitedMuitas requisições por minutoReduza a velocidade, distribua requisições ao longo do minuto
concurrencyMuitas requisições rodando ao mesmo tempoReduza a paralelização, aguarde os slots liberarem
Sobrecarga, com Retry-After: 5Carga temporária no serviço, não é culpa suaAguarde 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

  1. Registre o corpo completo do erro e o cabeçalho X-Request-Id para cada 429. O campo code separa rate_limited de concurrency.
  2. Verifique se sua chave é uma chave de teste. Se sim, espere 2 requisições simultâneas e 60 por minuto.
  3. Conte todos os programas que usam a chave, não apenas o que falhou.
  4. Procure streams não fechados, e loops que fazem retry instantaneamente sem atraso. Um loop de retry instantâneo transforma um 429 em cem.
  5. Confirme o saldo com X-Balance-USD ou GET /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.

Perguntas e respostas

O erro 429 é culpa sua ou do provedor?

Ambas são possíveis. Os códigos rate_limited e concurrency indicam que sua chave ultrapassou o limite. Um 429 com cabeçalho Retry-After também pode vir de sobrecarga temporária; esperar o tempo indicado e tentar novamente é a resposta correta.

Quanto tempo devo esperar antes de tentar novamente?

Se a resposta tiver um cabeçalho Retry-After, aguarde pelo menos esse número de segundos. Caso contrário, comece com um segundo e dobre o atraso a cada vez, com uma pequena oscilação aleatória.

Requisições rejeitadas custam dinheiro?

Não. Requisições falhas ou recusadas não são cobradas.

Posso aumentar meus limites?

Uma chave completa permite 8 requisições simultâneas e 300 por minuto, contra 2 e 60 para uma chave de teste. Além disso, distribua o trabalho em uma fila do seu lado.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.