OpenAI insufficient_quota e credit_balance_exhausted: por que tentar novamente não ajudará

A API openai retorna 429 com o tipo insufficient_quota de erro quando sua conta ficou sem créditos ou ultrapassou um limite de gastos ou uso. É o mesmo código de status que um limite de taxa, mas esperar alguns segundos não o corrigirá. O acesso só volta depois que alguém adiciona créditos, aumenta um limite ou o período mensal é redefinido. A OpenAI diz que tentar novamente após erros de cobrança, gastos ou cota não restaurará o acesso à API e que você deve inspecionar error.code para encontrar a causa específica. Para obter mais informações, consulte códigos de erro.

Qual é a aparência dos erros de cota da OpenAI

Cada um desses erros retorna 429. O error.type ainda pode ser insufficient_quota, então verifique error.code para saber qual deles você recebeu.

error.code O que significa Como o acesso volta
credit_balance_exhausted Sua organização não tem mais créditos pré-pagos. Adicionar créditos.
organization_spend_limit_exceeded Sua organização atingiu seu limite mensal de gastos em todos os projetos. Aumente ou remova o limite ou aguarde a redefinição mensal.
project_spend_limit_exceeded O projeto atingiu seu limite mensal de gastos. Outros projetos continuam funcionando. Aumente ou remova o limite do projeto ou aguarde a redefinição mensal.
organization_usage_limit_exceeded Sua organização atingiu o limite de uso mensal que o OpenAI atribuiu a ela. É separado dos limites de gastos que você definiu. Solicite um limite aprovado mais alto ou entre em contato com o suporte do OpenAI.

Compare-os com erros de "Limite de solicitações atingido", como rate_limit_exceeded e slow_down. Eles são temporários, e uma nova tentativa após uma breve espera geralmente funciona. Para obter mais informações, consulte erros de "Limite de taxa atingido" do OpenAI.

Como lidar com erros de quota da OpenAI

  1. Leia error.code, não apenas o status. Um 429 por si só não informa se você deve tentar novamente. Trate os 4 códigos na tabela como "parar" e os códigos de limite de taxa como "aguarde e tente novamente".
  2. Pare de repetir a tentativa. Não envie a solicitação novamente e não deixe um loop de repetição continuar chamando a API. Até que alguém corrija o problema de cobrança, cada requisição falha sempre da mesma forma.
  3. Pause as chamadas que falhariam. Um erro de cota significa que as próximas requisições da mesma organização ou projeto também falharão. Ignore-os em vez de enviar cada um e esperar pelo erro.
  4. Informe ao usuário. Explique que o recurso de IA está indisponível por enquanto e mantenha o restante do aplicativo funcionando.
  5. Crie um alerta para si mesmo. Registre o código com alta severidade ou chame por pager quem é responsável pelo faturamento. A correção está fora do seu código, então alguém precisa ser informado.

O SDK Python da OpenAI tenta novamente as respostas 429 2 vezes por padrão. Não importa quantas vezes ele tente novamente, seu código eventualmente obtém RateLimitError com o código de cobrança, e é aí que você para:

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

O sinalizador permanece ativado até que seu aplicativo seja reiniciado. Limpe isso de outra maneira se o aplicativo for executado por muito tempo, por exemplo, com uma ação de administrador depois que alguém corrigir a cobrança.

Como testar se seu aplicativo lida com erros de cota openai

Você raramente vê um erro de quota durante o desenvolvimento. Sua conta de teste tem créditos, e sua utilização está baixa. Portanto, a maneira como você testa o tratamento de cotas decide se você encontra os bugs antes dos usuários.

Approach O que você encontra Do que você sente falta
Aguarde o ambiente de produção Falhas reais Tudo, até que um usuário o acione e o recurso de IA permaneça inoperante até que alguém observe
Fazer mock da API em seus testes ou deixar seu agente de codificação escrever o mock Se o ramo de parada estiver em execução O corpo e os códigos de erro reais do OpenAI e a política de repetição do SDK. Seu aplicativo também precisa de uma opção somente de teste para acessar o mock.
Use seus créditos reais ou defina um pequeno limite de gastos Comportamento real Isso custa dinheiro e bloqueia todos os outros aplicativos que compartilham a organização ou o projeto
Interceptar o tráfego real do aplicativo e retornar erros de cota sob demanda URLs reais, seu SDK real e sua política de retry, e o próprio formato de erro da OpenAI Nada no aplicativo muda, portanto, ele não testa seu código de forma isolada. Mantenha seus testes de unidade para isso.

Teste no seu aplicativo

O Proxy de Desenvolvimento intercepta as solicitações do seu aplicativo para api.openai.com e retorna erros da OpenAI, enquanto seu aplicativo continua chamando as URLs reais. A predefinição openai-throttling mistura um erro credit_balance_exhausted com os erros de limite de taxa. Ele retorna 429 com tipo insufficient_quota e sem o cabeçalho Retry-After, para que você possa verificar se o aplicativo para em vez de tentar novamente.

Baixe o preset e inicie o Dev Proxy com ele:

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

Para testar apenas erros de cota, edite o arquivo da openai-errors.json predefinição e mantenha apenas a credit_balance_exhausted resposta. Para testar os códigos de limite de uso e gastos, adicione respostas com a mesma forma e um code diferente.

Em seguida, execute seu aplicativo como de costume e observe o que ele faz. Para instalar o Dev Proxy, consulte Configurar o Dev Proxy.

Próximas Etapas 

Testar como seu aplicativo lida com os limites de taxa do OpenAI

Consulte também

  • Última atualização em