Insufficient_quota y credit_balance_exhausted de OpenAI: por qué volver a intentarlo no ayudará

La API de OpenAI devuelve 429 con el tipo insufficient_quota de error cuando tu cuenta se quedó sin créditos o superó un límite de gasto o uso. Es el mismo código de estado que el de un límite de tasa, pero esperar unos segundos no lo soluciona. El acceso vuelve solo después de que alguien agregue créditos, aumente un límite o se restablezca el período mensual. OpenAI dice que volver a intentarlo tras errores de facturación, gasto o cuota no restaurará el acceso a la API y que debe inspeccionar error.code para encontrar la causa específica. Para obtener más información, vea Códigos de error.

¿Qué aspecto tienen los errores de cuota de OpenAI?

Cada uno de estos errores devuelve 429. El error.type puede seguir siendo insufficient_quota, así que comprueba error.code para saber cuál te ha salido.

Compárelos con errores de "Se alcanzó el límite de frecuencia", como rate_limit_exceeded y slow_down. Son temporales, y volver a intentarlo tras una breve espera suele funcionar. Para obtener más información, consulte Errores de "límite de tasa alcanzado" de OpenAI.

Cómo gestionar los errores de cuota de OpenAI

1. Lee error.code, no solo el estado. Un 429 solo no le indica si debe reintentarlo o no. Considera los 4 códigos de la tabla como "detener", y los códigos de límite de frecuencia como "esperar y volver a intentarlo".
2. Deja de volver a intentarlo. No envíe la solicitud de nuevo y no deje que un bucle de reintento siga llamando a la API. Hasta que alguien corrija el problema de facturación, todas las solicitudes fallan de la misma forma.
3. Pausa las llamadas que darían error. Un error de cuota significa que las siguientes solicitudes de la misma organización o proyecto también fallan. Omítelas en lugar de enviarlas una a una y esperar a que se produzca el error.
4. Informe al usuario. Explique que la característica de inteligencia artificial no está disponible por ahora y mantenga el resto de la aplicación en funcionamiento.
5. Avísate a ti mismo. Registre el código con una gravedad alta o avise a quien sea responsable de facturación. La solución está fuera de tu código, así que alguien tiene que saberlo.

El SDK de Python de OpenAI reintenta las 429 respuestas dos veces por defecto. Independientemente de lo que reintente, tu código acabará recibiendo RateLimitError el código de facturación, y ahí es donde debes detenerte:

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

La marca permanece establecida hasta que se reinicie la aplicación. Bórralo de otra forma si tu aplicación lleva mucho tiempo en funcionamiento, por ejemplo, mediante una acción de administración después de que alguien haya solucionado el problema de facturación.

Cómo probar que la aplicación controla los errores de cuota de OpenAI

Rara vez se ve un error de cuota durante el desarrollo. La cuenta de prueba tiene créditos y su uso es bajo. Por lo tanto, la forma en que pruebes la administración de cuotas determina si detectas los errores antes que tus usuarios.

Pruébalo en tu app

Dev Proxy intercepta las solicitudes de la aplicación a api.openai.com y devuelve errores de OpenAI, mientras que la aplicación sigue llamando a las direcciones URL reales. El openai-throttling preajuste mezcla un credit_balance_exhausted error con los errores de límite de tasa. Devuelve 429 con tipo insufficient_quota y sin encabezado Retry-After, por lo que puedes comprobar que la aplicación se detiene en lugar de volver a intentarlo.

Descargue el preajuste e inicie Dev Proxy con él:

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

Para probar solo los errores de cuota, edita el archivo openai-errors.json del preajuste y mantén solo la respuesta credit_balance_exhausted. Para probar los códigos de límite de gasto y de uso, añade respuestas con la misma estructura y un code diferente.

A continuación, ejecute la aplicación como de costumbre y observe lo que hace. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Pasos siguientes

Consulte también

• Errores de Límite de tasa alcanzado de OpenAI: qué significan y cómo administrarlos
• 429 Demasiadas solicitudes: lo que significa y cómo controlarlo
• Simular errores de las API de OpenAI
• GenericRandomErrorPlugin