Descripción general
El uso de la API está sujeto a límites de solicitudes. Estos límites restringen las solicitudes, los tokens u otros tipos de uso durante un período específico.
Una respuesta 429 puede indicar un límite de solicitudes temporal, un saldo prepagado agotado o un límite de gasto o uso. Revisa los detalles del error antes de volver a intentarlo o cambiar la configuración de facturación.
Identificar la causa
Lee el mensaje de error y error.code, si se proporciona. Los errores de facturación pueden seguir usando el valor más general insufficient_quota en error.type.
| Error o código | Qué significa | Qué hacer |
| Se alcanzó el límite de solicitudes o tokens | Las solicitudes superan un límite de solicitudes aplicable. | Distribuye las solicitudes y sigue las instrucciones de reintento que aparecen abajo. |
| credit_balance_exhausted | La organización no tiene créditos prepagados disponibles. | Agrega créditos en la configuración de facturación de la API. |
| organization_usage_limit_exceeded | La organización alcanzó el límite de uso asignado por OpenAI. | Solicita la aprobación de un límite de uso mayor. |
| organization_spend_limit_exceeded | La organización alcanzó el límite de gasto establecido. | Aumenta o elimina el límite, o espera al restablecimiento mensual. |
| project_spend_limit_exceeded | El proyecto alcanzó el límite de gasto establecido. | Aumenta o elimina el límite del proyecto, o espera al restablecimiento mensual. |
Reintentar tras un error de facturación, gasto o cuota no restablece el acceso. Primero, resuelve el problema con el saldo o límite informado. Los cambios en los límites de gasto establecidos pueden tardar en aplicarse.
Para cambiar un límite de gasto, necesitas permiso para administrar la configuración de la organización o el proyecto correspondiente. Si no tienes acceso, pídele ayuda a quien administra esa configuración.
Para comprar créditos prepagados, consulta: Configurar y administrar la facturación prepagada de la API.
Para conocer los distintos controles de gasto, consulta la guía de límites de gasto de la API.
Revisar los límites de solicitudes aplicables
Ve a la página Límites de tu organización para revisar su nivel de uso y sus límites actuales.
Los límites de solicitudes pueden aplicarse a nivel de organización y de proyecto. No son asignaciones para usuarios individuales. Los límites también varían según el modelo, y algunas familias de modelos comparten un límite.
Revisa qué límite identifica el error. Por ejemplo, las solicitudes por minuto y los tokens por minuto son límites distintos. Puedes alcanzar uno sin superar el otro.
Confirmar la organización que usa tu solicitud
Si perteneces a varias organizaciones, confirma que tus solicitudes usen la organización y el proyecto correctos.
Si tu clave de API usa una organización predeterminada, revisa la configuración de la organización predeterminada. Las organizaciones pueden tener distintos esquemas de facturación y niveles de uso.
Reducir los errores temporales de límite de solicitudes
Distribuir las solicitudes y evitar ráfagas
Distribuye las solicitudes a lo largo del tiempo en lugar de enviar muchas a la vez.
Los límites de solicitudes pueden aplicarse en períodos más cortos que el intervalo mostrado. Por ejemplo, un límite de 60 solicitudes por minuto también puede aplicarse en períodos de 1 segundo. Por lo tanto, una ráfaga breve puede provocar un error aunque tu uso promedio parezca estar por debajo del límite por minuto.
Los prompts largos y los límites de tokens de salida innecesariamente altos también pueden provocar errores de límite de tokens.
Reintentar después de una pausa
Para errores temporales de límite de solicitudes:
Busca un encabezado de respuesta Retry-After.
Si el encabezado contiene un tiempo de espera válido, espera al menos ese tiempo antes de volver a intentarlo.
Si el encabezado no aparece o no es válido, usa una espera exponencial con fluctuación aleatoria: aumenta la espera después de cada intento fallido y agrega una pequeña demora aleatoria.
Limita tanto la cantidad de reintentos como el tiempo total que dedicas a ellos.
Los SDK oficiales de OpenAI ya reintentan los errores de límite de solicitudes que cumplen los requisitos y respetan Retry-After cuando está presente. Ten en cuenta esos reintentos antes de agregar otro ciclo de reintentos.
Las solicitudes fallidas cuentan para los límites por minuto. Reenviar continuamente la misma solicitud puede prolongar el problema.
Para ver instrucciones y ejemplos de implementación, consulta la guía de límites de solicitudes de la API. Revisa cualquier biblioteca de reintentos de terceros antes de usarla en tu aplicación.
Revisar el tamaño del prompt y la salida
Elimina de tus prompts las instrucciones innecesarias, el contexto repetido y los ejemplos. Prueba el prompt revisado para confirmar que aún produce el resultado que necesitas.
Usa el parámetro de tokens de salida compatible con tu punto de acceso y modelo:
Chat Completions usa max_completion_tokens.
Responses usa max_output_tokens.
Evita establecer un límite mucho mayor de lo que necesita la solicitud. Estos parámetros incluyen tanto los tokens de razonamiento como la salida visible, así que contempla ambos cuando uses un modelo de razonamiento.
Revisar tu nivel de uso
Si los errores continúan después de reducir las ráfagas y revisar el uso de tokens, consulta en la página Límites las opciones disponibles para aumentar tus límites.
A medida que aumenta el gasto en la API, OpenAI puede subir automáticamente a una organización a un nivel de uso superior. Por lo general, esto aumenta los límites de solicitudes en la mayoría de los modelos.
Tu límite mensual de uso aprobado es independiente de los límites de solicitudes y tokens. Aumentar uno no confirma que el otro también haya cambiado.
Si el problema continúa
Antes de escalar el problema
Ten a la mano el mensaje de error exacto, los códigos de error, los ID de solicitud pertinentes, la hora del error con tu zona horaria y el límite correspondiente que aparece en tu cuenta. Anota los pasos que ya intentaste.
Contactar al equipo de Soporte de OpenAI
Contacta al equipo de Soporte de OpenAI mediante el Centro de ayuda si no puedes resolver el problema después de revisar el límite informado. No incluyas claves de API ni otros secretos de autenticación.