Error quota exceeded en OpenAI API: cómo resolver insufficient_quota

Si OpenAI API devuelve You exceeded your current quota o insufficient_quota, lee error.code antes de comprar créditos o reintentar. La categoría insufficient_quota puede acompañar a varios bloqueos: saldo prepago agotado, tope de gasto de la organización, tope del proyecto o límite de uso mensual aprobado por OpenAI. La referencia oficial de errores distingue estos casos y señala que repetir una solicitud sin corregir el saldo o el límite no devuelve el acceso.

Para recuperarlo, confirma primero qué organización y proyecto utiliza la aplicación. Después repón los créditos, modifica el tope alcanzado con autorización o solicita una ampliación del límite aprobado, según el código. Comprueba el resultado con una solicitud pequeña que conserve esa misma configuración antes de reanudar las automatizaciones. Pagar ChatGPT Plus o Pro no añade saldo a la API: son sistemas de facturación separados.

Qué significa el código que acompaña a insufficient_quota

El número HTTP 429 no identifica por sí solo la causa. También se usa para límites de solicitudes y tokens. Recupera el cuerpo completo del error si la herramienta solo muestra «quota exceeded»; una excepción llamada RateLimitError en Python tampoco basta para decidir que conviene reintentar.

Según la documentación actual de OpenAI, los códigos de facturación permiten elegir la primera acción:

Este cuerpo es un ejemplo ilustrativo, no una respuesta obtenida de una cuenta real:

{
  "error": {
    "type": "insufficient_quota",
    "code": "project_spend_limit_exceeded",
    "message": "..."
  }
}

Aquí el problema es el tope del proyecto. Recargar la organización no cambia ese ajuste. El campo type describe una categoría general; el campo code concreta el bloqueo.

Si solo tienes insufficient_quota, un código genérico como quota_exceeded o un mensaje genérico, todavía no puedes atribuirlo a saldo cero. Guarda el mensaje completo, identifica el servicio que lo emitió y comprueba saldo y límites en la organización y el proyecto de la solicitud. Si el texto describe solicitudes o tokens por minuto, sigue el diagnóstico de límites de frecuencia y reintentos en OpenAI API.

Antes de recargar: comprueba la organización y el proyecto

El saldo que ves en el navegador debe corresponder a la organización que recibe el consumo de la aplicación. Un panel con créditos no demuestra que el proceso que falla esté utilizando esa organización. Del mismo modo, un proyecto puede haber alcanzado su tope aunque otros proyectos sigan funcionando.

Compara estos datos de la aplicación con los del panel:

• Servicio y dirección de la API. Confirma si la solicitud va a OpenAI directamente o a una pasarela con su propia cuenta y sus propios límites.
• Clave configurada. Comprueba qué credencial tiene asignada el proceso que falla, sin copiarla en registros ni capturas. Desarrollo, producción y un conector pueden tener configuraciones distintas.
• Organización y proyecto. Verifica los identificadores, además del nombre visible. Si recibes la cabecera openai-organization, sirve para contrastar la organización de esa respuesta.
• Endpoint y modelo. Anótalos para repetir después una prueba equivalente; un cambio de ruta puede ocultar que el problema original sigue pendiente.

La referencia de autenticación permite seleccionar organización y proyecto mediante OpenAI-Organization y OpenAI-Project cuando perteneces a varias organizaciones o accedes a proyectos con una clave de usuario heredada. Estas cabeceras no convierten una clave limitada a un proyecto en una credencial válida para cualquier otro. Si necesitas localizar los identificadores o revisar esa selección, consulta cuándo usar Organization ID y Project ID.

Si utilizas Zapier, Make, n8n u otra integración, averigua si envía tu propia clave de OpenAI o emplea una cuenta gestionada por el proveedor. En el primer caso, revisa tu organización de OpenAI; en el segundo, comprueba la facturación y los límites de la integración. Un JSON compatible con OpenAI no demuestra que el error proceda de OpenAI.

Hay saldo, pero la API sigue bloqueada

Tener créditos no elimina un tope de gasto ni amplía el límite aprobado por OpenAI. Son controles distintos. Comprueba el código y el ajuste que corresponde a ese código; no aumentes todos los importes del panel por ensayo y error.

La guía de límites de gasto diferencia una alerta de un tope obligatorio:

Una notificación de presupuesto no prueba que exista un bloqueo. Para un tope configurado, importa si está activada la opción Enforce a hard limit. Además, los topes de organización y proyecto pueden aplicarse a la misma solicitud: cambiar el del proyecto no elimina un bloqueo de la organización.

Cambiar el tope que realmente se ha alcanzado

Necesitas permisos para gestionar los ajustes correspondientes y autorización para elevar el gasto. Si no los tienes, envía el código, los identificadores y el consumo observado a quien administra la organización o el proyecto.

Para un tope de organización, abre Organization limits. En Spend, selecciona Edit spend limit y revisa Monthly spend limit y Enforce a hard limit. Compara el importe con el consumo registrado. Si el servicio debe continuar y tienes autorización, amplía el límite o retira el tope obligatorio y guarda el cambio con Save.

Para un tope de proyecto, abre los ajustes del proyecto, selecciona el proyecto afectado y entra en Limits. En Spend → Edit spend limit, revisa los mismos controles y guarda la modificación autorizada.

Si el presupuesto debe mantenerse, conserva el trabajo pendiente hasta el siguiente ciclo mensual. OpenAI indica que los cambios deben propagarse antes de recuperar el tráfico. La aplicación del tope tampoco es instantánea: puede registrarse algo de consumo adicional mientras se actualiza su estado. No lo utilices como garantía de que el gasto jamás superará el importe configurado. Estas condiciones aparecen en la guía oficial de topes de gasto.

Solicitar más uso aprobado por OpenAI

Con organization_usage_limit_exceeded, abre Organization limits y revisa la opción de solicitar un límite de uso aprobado mayor. Si necesitas ayuda, contacta con soporte de OpenAI. Comprar créditos o modificar una alerta no aumenta esa asignación. Tampoco se trata de RPM o TPM: este código identifica el límite mensual de la organización, como explica la referencia de errores.

He recargado y sigue apareciendo quota exceeded

Si el código es credit_balance_exhausted y todavía no has repuesto el saldo, abre la facturación de la organización. Selecciona Buy credits o Add to credit balance, según aparezca en el panel, y compra el importe autorizado. Si no puedes gestionar la facturación, pide a la persona responsable de la organización que lo haga. Añadir un método de pago o crear una clave no sustituye a comprobar los créditos disponibles. La ayuda de prepago describe la compra de créditos y la actualización del saldo.

Comprueba el saldo contabilizado en la organización correcta, además de la confirmación del pago. La ayuda sobre facturación prepago indica que el saldo puede tardar unos minutos en actualizarse después de una compra. No establece una espera universal que garantice la recuperación; hacer otra compra porque la primera aún no aparece puede duplicar un gasto innecesariamente.

Si el saldo era negativo, la siguiente compra cubre primero el importe pendiente. Por ejemplo, con −3 USD y una compra de 10 USD quedarían 7 USD antes de cualquier consumo adicional. Es una cuenta ilustrativa de la regla de compensación, no un cargo extra. Los créditos comprados caducan al cabo de un año; que hubiera saldo en una captura antigua no prueba que siga disponible. Ambas condiciones están en la misma documentación de prepago.

Si el nuevo saldo ya aparece y el error continúa, vuelve a leer error.code. Un tope obligatorio o un límite de uso aprobado requiere su propia corrección. Si el código sigue indicando créditos agotados, contrasta la organización de la solicitud y conserva la compra y la respuesta para soporte, sin incluir datos completos de tarjeta ni credenciales.

Con la recarga automática activada, su límite mensual de compras puede impedir nuevas recargas. Ese límite restringe las compras automáticas, no el consumo de los créditos que ya tienes; las compras manuales no cuentan para él. Para revisar umbral, saldo objetivo, pagos rechazados y comprobar una compra automática posterior, utiliza la guía de fallos de recarga automática de OpenAI API.

Cómo comprobar que la llamada se ha recuperado

Después de que se actualice el saldo o el límite, envía una solicitud pequeña con la misma dirección de API, credencial, organización, proyecto, endpoint y modelo que fallaban. Hazlo solo con permiso para utilizar esa cuenta: una solicitud al modelo puede generar consumo y cargos. Reduce el contenido de prueba manteniendo los parámetros necesarios para que la respuesta pueda completarse.

El resultado permite elegir el siguiente paso:

Abrir el panel o recibir una lista de modelos no demuestra que una solicitud de pago al modelo vuelva a funcionar. Una llamada correcta tampoco garantiza que puedas reanudar toda la carga sin alcanzar RPM, TPM u otro límite.

Para pedir ayuda, guarda el código HTTP, error.code, error.type, el mensaje, la hora con zona horaria, organización, proyecto, endpoint, modelo y x-request-id si está disponible. Añade el cambio realizado y el resultado posterior. La referencia de la API recomienda registrar los identificadores de solicitud para facilitar el diagnóstico. Excluye la clave y la cabecera Authorization.

Preguntas frecuentes

¿Por qué falla la primera llamada con una clave recién creada?

Crear una clave no añade créditos ni amplía los límites de la organización o del proyecto. Lee el código del error y comprueba su facturación y sus límites. Si existen créditos gratuitos, OpenAI los utiliza antes que los comprados, pero su ayuda de prepago no promete un saldo gratuito a todas las cuentas nuevas.

¿Pagar ChatGPT Plus o Pro soluciona insufficient_quota?

No. ChatGPT y OpenAI API tienen facturación independiente. La suscripción no financia automáticamente las llamadas de la API; revisa el saldo y los límites de la organización en OpenAI Platform. La ayuda oficial de facturación explica esa separación.

¿Crear otra clave o cambiar de modelo elimina el bloqueo?

Una nueva clave del mismo proyecto no repone el saldo ni modifica sus topes. Cambiar de modelo tampoco amplía un límite de gasto o uso de la organización. Si otra configuración funciona, identifica qué organización, proyecto y ruta está utilizando antes de concluir que la causa se ha corregido.

¿Debo esperar si dice «quota exceeded, please try again later»?

No basta con esa frase para elegir una espera. Recupera el código completo y confirma qué servicio la emitió. Para créditos agotados o límites de facturación, la documentación de OpenAI exige corregir el saldo o el límite. Si identifica una restricción temporal de solicitudes o tokens, sigue las cabeceras y la política de reintentos para errores 429.