OpenAI insufficient_quota e credit_balance_exhausted: porque é que tentar novamente não ajuda

A API da OpenAI devolve 429 com o tipo de erro insufficient_quota quando a sua conta ficou sem créditos ou ultrapassou um limite de despesa ou utilização. É o mesmo código de estado que um limite de pedidos, mas esperar alguns segundos não resolve o problema. O acesso só volta depois de alguém adicionar créditos, aumentar um limite ou o período mensal ser reiniciado. A OpenAI diz que voltar a tentar após erros de faturação, despesa ou quota não restaura o acesso à API, e que deve inspecionar error.code para encontrar a causa específica. Para mais informações, consulte Códigos de erro.

Como se manifestam os erros de quota da OpenAI

Cada um destes erros devolve 429. O error.type ainda pode ser insufficient_quota, por isso verifica error.code para saberes qual recebeste.

error.code O que significa Como recuperar o acesso
credit_balance_exhausted A sua organização já não tem créditos pré-pagos. Adicionar créditos
organization_spend_limit_exceeded A sua organização atingiu o limite mensal de despesas em todos os projetos. Aumente ou remova o limite, ou aguarde pela reposição mensal.
project_spend_limit_exceeded O projeto atingiu o seu limite mensal de despesa. Outros projetos continuam a funcionar. Aumente ou remova o limite do projeto, ou aguarde pela reposição mensal.
organization_usage_limit_exceeded A sua organização atingiu o limite mensal de utilização que a OpenAI lhe atribuiu. É separado dos limites de gasto que definiste. Solicite um limite aprovado mais elevado ou contacte o suporte da OpenAI.

Compare-os com erros de "Limite de pedidos atingido", como rate_limit_exceeded e slow_down. Esses são temporários, e tentar novamente após uma curta espera normalmente funciona. Para mais informações, consulte erros 'Limite de taxa atingido' da OpenAI.

Como lidar com erros de quota OpenAI

  1. Leia error.code, não apenas o status. Um 429 sozinho não te diz se deves tentar novamente. Trate os 4 códigos na tabela como "parar" e os códigos do limite de taxa como "esperar e tentar novamente".
  2. Pare de tentar novamente. Não envie o pedido novamente e não deixe que um ciclo de retentativa continue a chamar a API. Até que alguém resolva o problema de faturação, todos os pedidos falham da mesma forma.
  3. Pausar as chamadas que falhariam. Um erro de quota significa que os próximos pedidos da mesma organização ou projeto também falham. Ignora-os em vez de enviar cada um e esperar pelo erro.
  4. Diz ao utilizador. Explica que a funcionalidade de IA não está disponível por agora e mantém o resto da tua aplicação a funcionar.
  5. Põe-te em alerta. Registe o código com uma gravidade elevada, ou alerte o responsável pela faturação. A correção está fora do teu código, por isso alguém precisa de saber.

O SDK Python da OpenAI tenta novamente 429 2 vezes por predefinição. Seja o que for que ele tente, o teu código acaba por obter RateLimitError com o código de faturação, e é aí que ficas:

import logging

import openai
from openai import OpenAI

client = OpenAI()
logger = logging.getLogger(__name__)

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}
billing_error: str | None = None


def ask(prompt: str) -> str:
    global billing_error
    if billing_error:
        raise RuntimeError("AI features are paused until billing is fixed.")
    try:
        response = client.responses.create(model="gpt-4.1", input=prompt)
        return response.output_text
    except openai.RateLimitError as error:
        if error.code in BILLING_CODES:
            billing_error = error.code
            logger.critical("OpenAI billing error: %s", error.code)
        raise

A bandeira mantém-se definida até a aplicação reiniciar. Elimina-o de outra forma se a tua aplicação estiver a funcionar durante muito tempo, por exemplo, com uma ação de administrador depois de alguém corrigir a faturação.

Como testar se a sua aplicação lida com erros de quota OpenAI

Raramente se vê um erro de quota enquanto se desenvolve. A tua conta de teste tem créditos e o teu uso é baixo. Assim, a forma como testas o tratamento das quotas decide se encontras os bugs antes dos teus utilizadores.

Approach O que encontra Do que sente falta
Aguardar o ambiente de produção Fracassos reais Tudo, até um utilizador a acionar, e a funcionalidade de IA ficar indisponível até alguém reparar
Simula a API nos teus testes, ou deixa o teu agente de programação escrever o mock Quer a sua ramificação de paragem funcione O corpo real de erro e os códigos 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.
Gaste os seus créditos reais ou defina um limite de despesa muito pequeno Comportamento real Custa dinheiro e bloqueia todas as outras aplicações que partilham a organização ou projeto
Intercete o tráfego real da sua aplicação e devolva erros de quota 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. O openai-throttling preset mistura um credit_balance_exhausted erro com os erros de limite de taxa. Ele responde 429 com o tipo insufficient_quota e sem o cabeçalho Retry-After, por isso podes verificar se a tua aplicação interrompe em vez de tentar novamente.

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"

Para testar apenas erros de quota, edite o ficheiro do openai-errors.json predefinido e mantenha apenas a credit_balance_exhausted resposta. Para testar os códigos de limite de gasto e utilização, adicione respostas com a mesma forma e um code diferente.

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

Passos seguintes

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

Ver também

  • Última atualização a