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 usos durante un periodo determinado.
Una respuesta 429 puede indicar un límite de solicitudes temporal, que se ha agotado el saldo prepagado o que se ha alcanzado un límite de gasto o uso. Consulta 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 relacionados con la facturación pueden seguir usando el valor general insufficient_quota en error.type.
| Error o código | Qué significa | Qué hacer |
| Se ha alcanzado el límite de solicitudes o tokens | Las solicitudes superan un límite de solicitudes aplicable. | Espacia las solicitudes y sigue las indicaciones de reintento que aparecen más adelante. |
| credit_balance_exhausted | A la organización no le quedan Créditos prepagados. | Añade Créditos en la configuración de facturación de la API. |
| organization_usage_limit_exceeded | La organización ha alcanzado el límite de uso asignado por OpenAI. | Solicita que se apruebe un límite de uso mayor. |
| organization_spend_limit_exceeded | La organización ha alcanzado el límite de gasto aplicado. | Aumenta o elimina el límite, o espera al restablecimiento mensual. |
| project_spend_limit_exceeded | El proyecto ha alcanzado el límite de gasto aplicado. | Aumenta o elimina el límite del proyecto, o espera al restablecimiento mensual. |
Reintentar una solicitud tras un error de facturación, gasto o cuota no restablece el acceso. Resuelve primero el problema indicado con el saldo o el límite. Los cambios en los límites de gasto aplicados pueden tardar en surtir efecto.
Para cambiar un límite de gasto, necesitas permiso para gestionar la configuración de la organización o el proyecto correspondiente. Si no tienes acceso, pídeselo a la persona que gestiona esa configuración.
Para comprar Créditos prepagados, consulta: Configurar y gestionar la facturación prepagada de la API.
Para conocer los distintos controles de gasto, consulta la guía sobre límites de gasto de la API.
Comprobar los límites de solicitudes aplicables
Ve a la página Límites de tu organización para consultar su nivel de uso y sus límites actuales.
Los límites de solicitudes pueden aplicarse tanto a la organización como al 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.
Comprueba qué límite identifica el error. Por ejemplo, las solicitudes por minuto y los tokens por minuto tienen 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 usan la organización y el proyecto previstos.
Si tu clave de API usa una organización predeterminada, comprueba la configuración de la organización predeterminada. Cada organización puede tener distintas condiciones de facturación y niveles de uso.
Reducir los errores temporales por límite de solicitudes
Espaciar 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 periodos más breves que el intervalo mostrado. Por ejemplo, un límite de 60 solicitudes por minuto también puede aplicarse en periodos de 1 segundo. Por tanto, una ráfaga breve puede provocar un error aunque tu uso medio parezca inferior al límite por minuto.
Los prompts largos y unos límites de tokens de salida innecesariamente altos también pueden causar errores de velocidad de tokens.
Volver a intentarlo tras una espera
Para los errores temporales por límite de solicitudes:
Comprueba si la respuesta incluye el encabezado 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 un retroceso exponencial con fluctuación: aumenta la espera tras cada intento fallido y añade un breve retraso aleatorio.
Limita tanto el número de reintentos como el tiempo total dedicado a ellos.
Los SDK oficiales de OpenAI ya vuelven a intentar las solicitudes que generan errores aptos por límite de solicitudes y respetan Retry-After cuando está presente. Ten en cuenta esos reintentos antes de añadir otro bucle de reintentos.
Las solicitudes fallidas cuentan para los límites por minuto. Reenviar continuamente la misma solicitud puede prolongar el problema.
Para consultar instrucciones y ejemplos de implementación, consulta la guía sobre 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 sigue produciendo 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 muy superior al que necesita la solicitud. Estos parámetros incluyen tanto los tokens de razonamiento como la salida visible, así que ten en cuenta ambos al usar 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 tu página Límites las opciones disponibles para aumentar tus límites.
A medida que aumenta el gasto en la API, OpenAI puede ascender automáticamente una organización a un nivel de uso superior. Esto suele aumentar los límites de solicitudes de 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 haya cambiado.
Si el problema continúa
Antes de escalar el problema
Ten a 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 has probado.
Contactar con el servicio de asistencia de OpenAI
Contacta con el servicio de asistencia de OpenAI a través del Centro de ayuda si no puedes resolver el problema después de comprobar el límite indicado. No incluyas claves de API ni otros secretos de autenticación.