Si una llamada a la API de OpenAI devuelve "You exceeded your current quota" o insufficient_quota, no empieces aumentando los reintentos. En la práctica suele ser una rama de disponibilidad de cuota: la organización, el proyecto, el presupuesto mensual, el saldo prepago, el estado de pago o la ruta de modelo no tienen cuota utilizable para esa solicitud.
La primera respuesta segura es abrir Billing y Limits en OpenAI Platform, confirmar la organización y el proyecto usados por la clave, revisar saldo prepago, presupuesto mensual, approved usage limit, estado de pago y acceso al modelo, y después enviar una solicitud mínima en el mismo proyecto. Solo cuando la cuota sea utilizable tiene sentido mirar RPM, TPM, concurrencia, cabeceras y backoff.
Al 29 de abril de 2026, la guía oficial de rate limits de OpenAI mantiene los límites exactos de cada cuenta en la página Platform Limits, mientras que production best practices trata billing limits y approved usage limits como controles de cuenta. El flujo operativo correcto mantiene esa frontera y no convierte números volátiles en una tabla permanente.
Respuesta rápida
| Pregunta | Respuesta |
|---|---|
| ¿Qué suele significar el error? | La ruta API no tiene cuota, saldo, presupuesto, estado de pago, proyecto o acceso de modelo utilizable. |
| ¿Es lo mismo que rate limit? | No. insufficient_quota es una rama de cuota/facturación; RPM y TPM son otra rama. |
| ¿Qué reviso primero? | Platform Billing, Limits, presupuesto mensual, organización, proyecto, clave y acceso al modelo. |
| ¿ChatGPT Plus o Pro lo arregla? | No automáticamente. Una suscripción de ChatGPT no financia por sí sola Platform API. |
| ¿Debo rotar claves? | No. Una clave nueva en el mismo proyecto sin cuota mantiene el mismo propietario del fallo. |
| ¿Cuándo miro rate-limit headers? | Después de confirmar cuota usable o cuando la evidencia apunte a presión de request/token. |
Confirma el propietario antes de cambiar código
La separación importante es disponibilidad frente a rendimiento. Un problema de rendimiento dice que la ruta está permitida, pero envías demasiadas solicitudes, demasiados tokens, demasiada concurrencia o bursts. Un problema de disponibilidad de cuota dice que esa ruta ahora mismo no tiene saldo, presupuesto, aprobación de pago, alcance de proyecto o acceso al modelo.
Si el cuerpo de error incluye insufficient_quota o el mensaje "You exceeded your current quota, please check your plan and billing details", el backoff puede hacer que la aplicación haga menos ruido, pero no crea cuota. Reintentar con más fuerza solo ensucia logs y oculta el estado de cuenta.
Cuando la evidencia sea RPM, TPM, remaining headers, reset windows, burst traffic o concurrencia, usa la página hermana OpenAI API rate limits. Quédate aquí cuando el cuerpo apunte a billing details, trial, prepaid credits, presupuesto mensual, organización, proyecto o acceso al modelo.
La documentación oficial encaja con este corte. La guía de rate-limits dirige a la página Limits para los límites vivos y a response headers para ventanas de request/token. Production best practices trata billing limits y approved usage limits como control de cuenta. Una página útil debe enseñar dónde mirar, no copiar una tabla que caduca.
Ejecuta cinco comprobaciones en orden
| Comprobación | Qué verificar | Por qué importa |
|---|---|---|
| Facturación | Billing de Platform está activo y el pago está sano. | La API se paga en Platform, no solo con una suscripción de ChatGPT. |
| Saldo prepago | Hay créditos, no han caducado y pertenecen a la cuenta activa. | El código puede estar bien y aun así fallar sin saldo utilizable. |
| Presupuesto mensual | El proyecto o la cuenta no tocó un cap propio ni un approved spend ceiling. | Se puede añadir saldo y dejar un presupuesto bajo que bloquea. |
| Organización y proyecto | La clave pertenece al mismo org/proyecto que acabas de revisar. | Mirar la organización equivocada hace parecer rota una cuenta financiada. |
| Ruta de modelo | El modelo pedido está disponible para ese proyecto y tier. | Tener saldo no garantiza acceso a todas las rutas de modelo. |
No conviertas estas cinco comprobaciones en "billing está bien". Una tarjeta válida puede existir sin saldo prepago. Puede haber saldo pero un presupuesto mensual agotado. Una organización puede estar financiada mientras la app usa una clave de otro proyecto. Un modelo barato puede funcionar y otro modelo más restringido fallar.
La prueba más limpia tras el panel es una solicitud mínima con la misma clave, organización, proyecto, familia de endpoint y modelo. Si funciona, vuelve a la aplicación y busca drift de variables de entorno, configuración de wrapper o secretos de despliegue. Si aún falla con insufficient_quota, el propietario sigue siendo cuota de cuenta o acceso de ruta.
Orden de recuperación
Arregla la rama en el mismo orden en que la diagnosticaste.
- Confirma la organización y el proyecto correctos en OpenAI Platform.
- Abre Billing y revisa saldo, método de pago, estado de créditos e invoices.
- Abre Limits y revisa approved usage limit, presupuesto mensual, disponibilidad de modelo y project scope.
- Si acabas de añadir prepaid credits, espera la propagación antes de declarar que no funcionó.
- Ejecuta una solicitud mínima del mismo proyecto antes de reiniciar colas o workers.
- Solo después ajusta RPM, TPM, concurrencia, token budget o response-header backoff.
El orden es conservador a propósito. Evita dos errores caros: cargar saldo en la cuenta equivocada y desplegar lógica de reintentos para un problema de estado de cuenta. Los detalles volátiles, como compra mínima, expiración de créditos o usage tier, deben verificarse en Billing y Help Center durante el incidente.
Si la clave es nueva o el trial state no está claro, consulta OpenAI API key free trial. Si la organización o el project scope no cuadran, separa esa configuración antes de tocar código.
Wrappers e integraciones
Zapier, Make, n8n, gateways internos y proveedores compatibles con OpenAI pueden mostrar un mensaje de cuota estilo OpenAI aunque el propietario de facturación no sea evidente. La pregunta es quién posee la credencial que realmente se envía a OpenAI.
Si la integración usa tu propia OpenAI API key, diagnostica primero tu cuenta de Platform. Si usa una cuenta gestionada por el proveedor, diagnostica el plan del wrapper, connector quota o workspace budget. Si permite ambos modos, prueba una solicitud mínima directa contra OpenAI Platform con tu clave y compara con la ruta del wrapper.
No asumas que el script local, production worker, CI y app pública usan el mismo presupuesto. Producción puede usar otro proyecto, una clave vieja, otra organización o un gateway con cap propio. La prueba directa elimina el wrapper y demuestra si Platform quota está disponible.
Reglas de parada
Cuando el cuerpo del error apunta a quota o billing, detén esto:
- rotar claves dentro del mismo proyecto sin cuota;
- aumentar retry count para atravesar un error de cuota;
- comprar una suscripción de ChatGPT esperando crédito automático para Platform API;
- usar una tabla pública de cuotas como prueba de tu estado de cuenta;
- pedir higher rate limits antes de confirmar usable spend.
Haz esto en su lugar: guarda exact error body, timestamp, organization, project, key source, endpoint, model y dashboard state; registra si una solicitud mínima directa funciona; compara wrapper path y direct Platform path; anota cualquier cambio reciente de billing y cuánto esperaste la propagación; escala con evidencia, no solo con una captura.
Paquete de evidencia
Para soporte o limit increase, incluye exact error text, error type, HTTP status, model, endpoint family, project, organization, timestamp with timezone, Billing page state, Limits page state, cambios recientes de pago o créditos y el resultado del minimal same-project retest.
Si la meta real es más throughput después de tener cuenta usable, el paquete cambia: requests per minute, tokens per minute, concurrency, queue size, reset headers y cómo ya redujiste bursts o token output. Eso pertenece a rate-limit, no a quota.
Preguntas frecuentes
¿Por qué aparece justo después de crear una API key?
Una API key solo es una credencial. No demuestra billing, credits, budget ni acceso de modelo. Revisa la misma organización y proyecto que crearon la clave.
¿Añadir créditos lo arregla al instante?
Puede necesitar una propagación breve. Vuelve a probar el mismo proyecto y confirma que los créditos están en la cuenta y proyecto que usa la clave.
¿insufficient_quota es igual a too many requests?
No. Too many requests es una rama de rendimiento. insufficient_quota es una rama de disponibilidad. El HTTP status puede parecerse, pero la solución es distinta.
¿Por qué el dashboard muestra margen y la app falla?
La app puede usar otra organización, proyecto, clave, wrapper account, model route o variable de entorno. Compara una solicitud mínima directa con la ruta de la aplicación.
¿Cuándo debo pedir un higher limit?
Solo cuando la cuenta tiene cuota usable y la evidencia apunta a throughput o approved usage ceiling. Si el propietario es payment, balance, monthly budget o project scope, arregla eso primero.