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.

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.

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 

Consulte também

• Erros de "Limite de taxa atingido" do OpenAI: o que eles significam e como lidar com eles
• 429 Solicitações em excesso: o que significa e como lidar com isso
• Simule erros das APIs da OpenAI
• GenericRandomErrorPlugin