Herramientasgemini
Gemini quota: límites de API y cómo resolver errores
Entiende la cuota de Gemini API, localiza los límites de tu proyecto y aprende a gestionar un error 429 sin exponer datos ni claves de acceso.
- Autor: humAIns
- 8 min de lectura
índice · 6 apartados
La cuota de Gemini API son los límites que restringen el uso que un proyecto puede hacer de modelos y funciones de la API. Si recibes un error 429, comprueba qué límite se ha alcanzado en Google AI Studio antes de cambiar de clave o añadir facturación: los límites pueden depender del proyecto y del modelo, y no existe una explicación única para cada 429. Esta guía explica cómo diagnosticarlo y cómo diseñar reintentos sin exponer información ni generar una tormenta de llamadas.
La palabra «cuota» puede llevar a confusión porque Gemini API y la aplicación Gemini para usuarios son productos distintos. Los límites de consumo de la aplicación no son los límites de tasa de la API que usa una integración. Tampoco una clave representa una bolsa de cuota independiente: sirve para autenticar solicitudes asociadas a un proyecto.
Qué significa cuota en Gemini API
Google mide los límites de la API por proyecto, no por clave. Si dos claves pertenecen al mismo proyecto, crear una tercera no reparte ni reinicia los límites. El proyecto es la unidad que reúne las credenciales, los colaboradores y, según la configuración, la facturación y el nivel de uso aplicable.
Los límites pueden cambiar según el modelo elegido, el nivel de uso y otras condiciones de la cuenta. Las variantes experimentales y de vista previa pueden tener límites más restrictivos. La documentación de modelos Gemini distingue modelos y estados —por ejemplo, estables, preview o experimentales—; verifica el identificador exacto y la disponibilidad del modelo que ejecuta tu integración, no solo el nombre que aparece en una guía antigua.
No confundas tener facturación activa con disponer de capacidad ilimitada. La facturación puede habilitar niveles de pago y sus límites asociados, pero no hace desaparecer cada límite de solicitudes, tokens o gasto. Además, una clave estándar no identifica por sí sola a una persona: revisa quién puede acceder al proyecto y cómo se almacenan las credenciales.
Peticiones, tokens y otros límites
La documentación oficial describe varias dimensiones que pueden aplicarse a una API o modelo. Entre ellas están las solicitudes por minuto (RPM), los tokens de entrada por minuto (TPM) y las solicitudes por día (RPD). Algunos modelos o funciones tienen dimensiones adicionales, como límites de imágenes, tokens por día o restricciones particulares de herramientas integradas. También pueden existir límites de gasto, de acuerdo con la cuenta y el nivel de uso.
Los límites se evalúan independientemente: estar por debajo de las solicitudes por minuto no evita un error si ya se ha alcanzado, por ejemplo, un límite de tokens. Las cuotas diarias se reinician a medianoche, hora del Pacífico, según la documentación consultada el 16 de noviembre de 2026. Los valores exactos no son universales ni garantizados: Google advierte que dependen del proyecto y modelo y que la capacidad real puede variar.
Por eso no uses una tabla copiada de internet como promesa de capacidad para tu cuenta. La referencia útil es el límite activo que se muestra para el proyecto y modelo concretos. Consulta límites de Gemini API antes de estimar capacidad o comprometer un tiempo de respuesta.
Dónde comprobar consumo y límites
En Google AI Studio, abre la vista de límites de frecuencia: AI Studio Rate Limit. La página oficial de límites enlaza directamente a esa vista y permite consultar los límites activos. Comprueba que tienes seleccionado el proyecto correcto y revisa el modelo que realmente usa tu aplicación. Los nombres de navegación pueden cambiar, por lo que conviene seguir el enlace oficial en lugar de depender de instrucciones de interfaz desactualizadas.
Para revisar el estado de facturación, entra en el apartado de facturación de AI Studio o en Google Cloud asociado al proyecto. La documentación de facturación de Gemini API describe los niveles y cómo se vincula una cuenta de facturación. Los proyectos ligados a una cuenta pueden heredar el nivel correspondiente; cambiar el proyecto de cuenta puede cambiar el nivel y sus límites. Si el equipo administra varios proyectos, registra cuál usa cada entorno para no diagnosticar el proyecto equivocado.
La página de claves de AI Studio ayuda a identificar el proyecto vinculado a una credencial. Google explica en su guía de gestión de claves de Gemini que las claves se asocian a proyectos y que deben tratarse como secretos. No compartas aquí la clave, el encabezado de autenticación ni una captura que los revele: basta con anotar el nombre interno del proyecto, el modelo, la hora y el texto no sensible del error.
Diagnóstico de un error 429
El estado HTTP 429 significa que la solicitud no se puede atender por un límite de uso, pero el detalle importa. El código de error, el mensaje y la respuesta completa pueden indicar si el límite es de ritmo, de cuota diaria u otro recurso agotado. La guía de Google sobre errores de API documenta distintas categorías de error y recomienda tratar el código devuelto, no asumir que todo 429 se resuelve igual.
Sigue este orden para encontrar la causa:
- Registra el momento del error, el modelo y el nombre del proyecto. No registres la clave ni datos personales enviados en la petición.
- Lee el código y el mensaje de respuesta. Distingue un límite de solicitudes de uno de tokens, de una cuota diaria o de un límite ligado a una función.
- Abre los límites activos en AI Studio y confirma que estás mirando el proyecto y el modelo correctos.
- Comprueba el ritmo real de llamadas y el tamaño aproximado de las entradas y salidas. Un proceso en paralelo puede agotar el límite aunque cada trabajador parezca ir despacio.
- Revisa el estado de cuenta y facturación si el error o la consola apuntan a un requisito de proyecto, nivel o gasto. No cambies de nivel a ciegas ni supongas que pagar elimina el límite concreto.
- Corrige la carga o espera a que se libere o restablezca el límite aplicable. Solo solicita un aumento si la opción está habilitada y has comprobado que la carga legítima lo requiere.
Un 429 intermitente bajo picos puede requerir control de concurrencia; uno repetido tras alcanzar un límite diario puede requerir esperar al reinicio o rediseñar el volumen. En cambio, errores de credenciales, permisos, modelo inexistente o facturación pueden devolver otros códigos HTTP. Clasificar primero evita reintentos inútiles y cargos inesperados.
Reintentos seguros y control de carga
No vuelvas a enviar una solicitud fallida en un bucle inmediato. Implementa una espera progresiva: aumenta el intervalo entre intentos, añade una pequeña variación aleatoria para que muchos procesos no reintenten simultáneamente y establece un máximo de intentos. Si la respuesta incluye información útil sobre cuándo reintentar, respétala. Detén la operación y registra el fallo cuando se agoten los intentos; evita que un error temporal se convierta en cientos de solicitudes.
Ejemplo ficticio: una automatización de clasificación procesa una cola de documentos y recibe un 429 para el proyecto de pruebas. El trabajador pausa esa tarea, espera un intervalo creciente con variación, y la reintenta dentro de un máximo configurado. Mientras tanto, reduce el número de tareas simultáneas y evita volver a enviar documentos ya procesados. No es una instrucción para una biblioteca concreta: ajusta el manejo al SDK, tipo de operación y código de error que realmente utilizas.
También puedes reducir solicitudes duplicadas, agrupar trabajo cuando la API y el caso de uso lo permitan, limitar la concurrencia y reducir el contexto o longitud de salida si el problema es el consumo de tokens o gasto. Monitoriza por proyecto y modelo la tasa de errores, la latencia, las solicitudes y el consumo; añade alertas antes de que un pico interrumpa el proceso. No des por hecho que cambiar de modelo es neutro: verifica primero su capacidad, comportamiento y coste.
Si el volumen habitual supera los límites activos, revisa los requisitos del nivel y la opción de solicitar más capacidad descrita en la documentación oficial. La solicitud no garantiza un aumento. Actualiza después la configuración con los límites confirmados y conserva un mecanismo de control para los picos.
Preguntas frecuentes
¿La cuota gratuita de Gemini API es ilimitada?
No. El acceso gratuito se aplica a determinados modelos y usos dentro de límites que pueden variar. Consulta la vista de AI Studio para el proyecto y el modelo antes de iniciar una integración de producción.
¿Por qué aparece 429 aunque haya pagado?
La facturación no equivale a capacidad ilimitada. Puede que se haya alcanzado un límite de solicitudes o tokens, una cuota diaria, un límite de gasto u otra restricción. Revisa el detalle del error y los límites activos, además del estado de facturación.
¿Pagar aumenta automáticamente todos los límites?
No. La documentación vincula niveles y límites con condiciones de cuenta y proyecto, y algunos aumentos requieren cumplir criterios o pedirlos. Confirma el nivel efectivo y no presupongas que se actualizará cada dimensión al activar facturación.
¿Puedo compartir mi clave con el equipo?
Evita distribuir una clave por chat, correo o repositorio. Usa gestión centralizada de secretos y acceso apropiado al proyecto. Si la credencial se expone, rótala y revisa actividad y facturación; los detalles están en la guía de API key de Gemini.
Para comparar opciones generales de API y sus condiciones, consulta nuestra guía de APIs de IA gratis y el artículo sobre precios de Gemini. Este post se centra en diagnosticar límites y errores, no en comparar planes.
El curso de IA aplicada al marketing aborda usos profesionales de IA en marketing; no es un curso de programación ni de integración de APIs.