Erros de 'Limite de taxa atingido' da OpenAI: o que significam e como lidar com eles

A API da OpenAI devolve 429 com "Limite de pedidos atingido" quando a sua organização enviou mais pedidos ou mais tokens por minuto do que os seus limites permitem. Os limites aplicam-se à sua organização, não a cada utilizador. Estes erros são temporários. Se esperar e enviar o pedido novamente, normalmente é bem-sucedido. Alguns outros 429 erros da OpenAI são relacionados com a faturação, e esses não desaparecem quando se espera. Para mais informações, consulte Códigos de erro.

Como se apresentam os erros de limite de taxa de pedidos da OpenAI

Status Erro O que significa Tentar novamente?
429 rate_limit_exceeded, requisições por minuto (RPM) Enviaste demasiadas solicitações num minuto. Sim, depois Retry-After
429 rate_limit_exceeded, tokens por minuto (TPM) Os teus pedidos usaram tokens a mais num minuto. A mensagem mostra o teu limite, quantos tokens usaste e quantos o pedido solicitou. Sim, depois de Retry-After. Pedidos mais pequenos ajudam.
429 slow_down (tipo rate_limit_error) O teu tráfego cresceu demasiado depressa, mesmo estando dentro dos teus limites de RPM e TPM. Sim, a uma taxa mais baixa
503 server_is_overloaded (tipo service_unavailable_error) Os servidores da OpenAI estão ocupados. Sim, com atrasos maiores a cada vez
429 credit_balance_exhausted, erros de limite de gastos ou de utilização (tipo insufficient_quota) Já não tens créditos ou ultrapassaste um limite. Não. Veja a OpenAI insufficient_quota e credit_balance_exhausted.

A maioria destes erros partilha o 429 mesmo estado, por isso não os consegue distinguir apenas pelo estado. Leia error.code no corpo da resposta.

Como lidar com erros de limite de pedidos da OpenAI

  1. Confirma error.code primeiro. Se for um código de faturação como credit_balance_exhausted, pare de repetir a tentativa e informe o utilizador. Tentar novamente após um erro de faturação não restaura o acesso.
  2. Siga Retry-After quando estiver presente. Se estiver em falta, usa recuo exponencial com jitter e limita o número de tentativas.
  3. Abrandar após slow_down. Reduz a taxa de pedidos e depois aumenta gradualmente. A regra geral da OpenAI acima de 1M de TPM de entrada é aumentar o tráfego em no máximo 50% a cada 15 minutos.
  4. Envie menos tokens após um erro TPM. Prompts e respostas mais curtas permitem que mais pedidos caibam em cada minuto.
  5. Afaste-se ainda mais depois de um 503. Aumenta o atraso entre tentativas e consulta a página de estado do OpenAI.
  6. Diz ao utilizador o que está a acontecer. "Ocupado, a tentar novamente em 5 segundos" é melhor do que um spinner que nunca acaba.

O SDK OpenAI Python repete as tentativas após erros de ligação e respostas 408, 409, 429 e 5xx 2 vezes por defeito, com um curto backoff exponencial. Pode mudá-lo com max_retries. Quando as tentativas acabam, o SDK lança RateLimitError para uma 429 e InternalServerError para um 503, por isso o teu código ainda precisa de um plano:

import openai
from openai import OpenAI

client = OpenAI(max_retries=3)

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}


def summarize(text: str) -> str | None:
    try:
        response = client.responses.create(model="gpt-4.1", input=text)
        return response.output_text
    except openai.RateLimitError as error:
        if error.code in BILLING_CODES:
            raise  # Retrying won't help: alert and tell the user
        return None  # Still throttled after retries: show "busy, try again"
    except openai.InternalServerError:
        return None

Como testar se a sua aplicação lida com os limites de taxa da OpenAI

Raramente atinges o limite de taxa do OpenAI enquanto desenvolves. És o único utilizador, e os teus prompts são curtos. Assim, a forma como testas a gestão de rate limits decide se encontras os bugs antes dos teus utilizadores.

Approach O que encontra Do que sente falta
Aguardar a produção Fracassos reais Tudo, até que um utilizador clique nele
Simula a API nos teus testes, ou deixa o teu agente de programação escrever o mock Se o seu branch de retry correr Os corpos e códigos de erro reais do OpenAI, e a política de retentativas do teu SDK. A tua aplicação também precisa de um switch só de teste para chegar ao mock.
Faz pedidos à API real até que te limite Comportamento real Não podes ativar um erro específico a pedido, e cada pedido custa tokens
Intercete o tráfego real da sua aplicação e devolva erros OpenAI quando solicitado URLs reais, o seu SDK real e política de retentativa, e o próprio formato de erro da OpenAI Nada na tua aplicação muda, por isso não testa o teu código isoladamente. Guarda os testes unitários para isso.

Experimente na sua app

O Proxy de desenvolvimento interceta os pedidos da sua aplicação para api.openai.com e devolve erros do OpenAI, enquanto a sua aplicação continua a chamar os URLs reais. A openai-throttling predefinição falha na maioria dos pedidos com um erro escolhido aleatoriamente de entre os erros TPM e RPM rate_limit_exceeded, slow_down, credit_balance_exhausted e 503server_is_overloaded, no próprio formato da OpenAI. As respostas de limitação de taxa 429 incluem um cabeçalho Retry-After, e se a sua aplicação tentar novamente antes de esse tempo terminar, o Dev Proxy assinala-o.

Descarregue a predefinição e inicie o Dev Proxy com ela:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Depois executa a tua aplicação como de costume e vê o que faz. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Para testar como a sua aplicação se comporta quando fica sem tokens por minuto, com base no prompt e nos tokens de conclusão que os seus pedidos utilizam, consulte Testar os limites de tokens do modelo de linguagem.

Passos seguintes

Testa como a tua aplicação lida com os limites de taxa do OpenAI

Ver também

  • Última atualização a