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.

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.

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

Ver também

• Erros de 'Limite de taxa atingido' da OpenAI: o que significam e como lidar com eles
• 429 Demasiados pedidos: o que significa e como lidar com isso
• Simular erros das APIs da OpenAI
• GenericRandomErrorPlugin