Un 429 de la API de Gemini no te dice, por sí solo, cuántos minutos debes esperar. Antes de cambiar una clave, activar la facturación o reducir el tráfico, anota cinco datos: superficie de producto, proyecto o cuenta, modelo o función exactos, métrica o carril de servicio y ventana de reinicio o de evidencia. Si falta uno, todavía no sabes qué límite has alcanzado.
En Gemini Developer API, el valor aplicable está en la fila del proyecto de Google Cloud y del modelo exacto de la pantalla de límites de Google AI Studio. Gemini Apps, Firebase AI Logic y Vertex AI cuentan el uso de otra manera. No existe una sola cifra que pueda llamarse «el límite de Gemini» para las cuatro rutas.
| Ruta que usas | Dónde está la evidencia activa | Primera acción |
|---|---|---|
| Gemini Developer API | Fila exacta de proyecto y modelo en AI Studio | Identificar si se agotó RPM, TPM de entrada, RPD, IPM, TPD, gasto, Priority o Batch |
| Gemini Apps | Ajustes → Límites de uso en la aplicación | Comprobar la función afectada y la hora de recuperación indicada |
| Firebase AI Logic | Límite por usuario de Firebase más la cuota del proveedor superior | Revisar ambas capas; manda la más baja |
| Vertex AI | Dynamic Shared Quota o Provisioned Throughput en Google Cloud | Diagnosticar la capacidad compartida o contratada por separado |
Regla de parada: no rotes claves ni mantengas un bucle de reintentos a ciegas. 429 RESOURCE_EXHAUSTED orienta hacia cuota, frecuencia, gasto u otra condición de admisión. 503 UNAVAILABLE orienta hacia capacidad o disponibilidad temporal. Separa las dos ramas antes de modificar la carga.
Consulta la fila activa del proyecto, no una tabla copiada
La documentación oficial de límites de Gemini Developer API define el mecanismo. La vista autenticada de AI Studio muestra los valores que corresponden a un proyecto y un modelo concretos. Una tabla pública puede explicar las siglas, pero no demuestra que tu proyecto tenga el mismo nivel, estado de cuenta, modelo preview o capacidad activa.
Los límites de Developer API suelen aparecer en tres dimensiones independientes:
- RPM (requests per minute) cuenta llamadas. Muchas peticiones pequeñas pueden agotar RPM antes que los tokens.
- TPM de entrada (input tokens per minute) cuenta el prompt y el contexto de entrada. Un número menor de peticiones grandes puede agotar primero este carril.
- RPD (requests per day) se aplica cuando la fila activa tiene un límite diario. Según el contrato oficial actual, el contador se reinicia a medianoche, hora del Pacífico.
Algunas filas de modelo o función también incluyen IPM (images per minute) o TPD (tokens per day). Superar cualquiera de las dimensiones aplicables puede generar una respuesta de límite. Los modelos preview y experimentales pueden tener valores más estrictos; copia el identificador exacto de la solicitud en lugar de deducirlo por el nombre de la familia.
La cuota se aplica por proyecto de Google Cloud, no por clave de API. Dos claves del mismo proyecto consumen el mismo fondo. Una segunda clave puede servir para rotación de credenciales o separación de servicios, pero no crea más RPM, TPM ni RPD. Si el bloqueo aparece como un mensaje de la interfaz de AI Studio y no como una respuesta de la API, utiliza la guía específica para recuperarte de un límite de Google AI Studio.
Google también advierte que el límite publicado no equivale a capacidad garantizada. La fila es un techo y una condición de admisión; no promete que todas las peticiones por debajo de ese techo se atenderán durante un problema regional o de capacidad del servicio.
Los niveles y las condiciones de gasto cambian
Con fecha de 15 de julio de 2026, la página pública de Google muestra estas condiciones para optar a cada nivel:
| Nivel | Condición pública en esa fecha | Qué debes verificar en tu cuenta |
|---|---|---|
| Free | Proyecto activo o estado de free trial | Modelos disponibles y valores reales de sus filas |
| Tier 1 | Cuenta de facturación activa y vinculada | Nivel y fila del modelo tras activar la facturación |
| Tier 2 | Al menos 100 USD pagados y 3 días desde el primer pago correcto | Estado de la cuenta y nivel que muestra Google |
| Tier 3 | Al menos 1.000 USD pagados y 30 días desde el primer pago correcto | Estado de la cuenta y nivel que muestra Google |
La misma página describe actualmente un límite basado en gasto y evaluado en una ventana móvil de 10 minutos: 10 USD para Tier 1 y 200 USD para Tier 2 y Tier 3. Tanto las cantidades como su ámbito pueden cambiar. Vuelve a contrastar la página oficial de límites y el proyecto autenticado antes de incluirlas en una prueba de carga o un procedimiento de incidentes.
La facturación cambia la elegibilidad; no elimina todos los límites. Un proyecto de pago aún puede agotar RPM, TPM de entrada, RPD, la ventana de gasto, Batch o la capacidad del carril. Si tu pregunta es qué modelo puede usarse sin facturación, trátala por separado con la guía del nivel gratuito de Gemini API.
Separa minuto, día, gasto y carril de servicio
Una solicitud puede estar dentro de los contadores por minuto y aun así ser rechazada por un límite diario o por la ventana de gasto. Standard, Priority y Batch tampoco son tres nombres de una misma bolsa: son carriles que deben medirse por separado.
| Contador o carril | Qué controla | Evidencia que conviene guardar | Error habitual |
|---|---|---|---|
| RPM | Llamadas online por minuto | Distribución temporal y fila RPM activa | Medir solo RPS medio e ignorar ráfagas |
| TPM de entrada | Prompt y contexto por minuto | Distribución de tokens de entrada | Suponer que todas las peticiones miden lo mismo |
| RPD | Peticiones diarias cuando existe | Fila RPD y reinicio en hora del Pacífico | Creer que un backoff corto repara un tope diario |
| Ventana de gasto | Admisión por gasto durante la ventana aplicable | Nivel de facturación y regla oficial actual | Confundirla con el presupuesto mensual |
| Priority | Límite independiente de servicio prioritario | Tier solicitado y x-gemini-service-tier devuelto | Tratarlo como capacidad extra ilimitada |
| Batch | Fondo separado para trabajo asíncrono | Jobs concurrentes, tamaño de archivos y tokens en cola | Enviar a Batch una tarea interactiva urgente |
La documentación de Priority inference fija actualmente el límite Priority predeterminado en 0,3 veces el límite Standard del modelo y nivel correspondientes. Cuando se agota esa capacidad, una solicitud puede atenderse como Standard en lugar de fallar. Registra x-gemini-service-tier si el carril afecta a la latencia o al coste.
Batch sirve para trabajo no urgente porque utiliza una cuota distinta a la de las llamadas interactivas. A 15 de julio de 2026, la documentación de Batch API indica 100 solicitudes batch simultáneas, 2 GB por archivo de entrada, 20 GB de almacenamiento total y límites de tokens en cola según modelo y nivel. Son condiciones fechadas, no constantes permanentes.
Una prueba de carga útil registra algo más que el RPS objetivo: proyecto y modelo exactos, percentiles p50 y p95 de tokens de entrada, patrón de ráfagas, carril solicitado, latencia p95, volumen diario, exposición de gasto, proporción de reintentos y necesidad real de respuesta síncrona.
Convierte la fila activa en un presupuesto de capacidad
Cuando tengas los valores del proyecto, calcula qué techo por minuto se alcanza primero:
Techo de peticiones = min(RPM activo, TPM de entrada activo ÷ tokens de entrada medios por petición)
El resultado es un punto de orientación matemática, no el objetivo de producción. El tamaño de entrada varía, el tráfico llega en ráfagas, los reintentos amplifican carga y la capacidad disponible puede ser menor que el valor mostrado. Elige el margen operativo según la variabilidad observada y el riesgo del negocio; Google no prescribe un porcentaje universal.
Ejemplo calculado con supuestos explícitos
Supón que la fila activa muestra 60 RPM y 120.000 TPM de entrada, y que las peticiones observadas tienen una media de 4.000 tokens de entrada:
- El techo definido por RPM es de 60 peticiones por minuto.
- El techo definido por TPM es 120.000 ÷ 4.000 = 30 peticiones por minuto.
- Manda el menor, así que el techo previo al margen es de 30 peticiones por minuto.
- Si el equipo decide reservar un 20 % de margen para este ejemplo, el objetivo inicial será 24 peticiones por minuto, es decir, 0,4 RPS.
- Con una latencia p95 observada de 2 segundos, la concurrencia estable estimada es 0,4 × 2 = 0,8 solicitudes en curso. En la práctica, empieza con un límite de concurrencia de 1 y mide cola, ráfagas y reintentos.
Ese 20 % es un supuesto de ingeniería para explicar el cálculo, no una recomendación de Google. Una carga pública con picos puede necesitar más margen; una cola offline uniforme y con entradas controladas podría usar otro valor.
El cálculo por minuto es solo la primera puerta. A 24 peticiones por minuto, una carga continua intentaría teóricamente 34.560 peticiones al día. Compárala con la fila RPD activa y revisa la ventana de gasto de forma independiente. Que una prueba de diez minutos funcione no significa que ese ritmo sea sostenible durante 24 horas.
Cuando el tamaño de las peticiones varía, usa percentiles además de la media:
| Observación | Qué aporta |
|---|---|
| Tokens de entrada medios | Estimación inicial en estado estable |
| Tokens de entrada p95 | Riesgo de agotar TPM durante picos normales |
| Entrada máxima permitida | Evita que una clase de trabajo consuma todo el minuto |
| Latencia p95 | Convierte RPS seguro en un límite inicial de concurrencia |
| Tasa de reintentos | Muestra la amplificación durante fallos parciales |
| Tasa de aciertos de caché | Indica si puede sacarse contexto repetido del camino crítico |
Recalcula cuando cambien el modelo, la plantilla de prompt, el contexto, el uso de herramientas, la mezcla de tráfico, el nivel o el carril. Planificar capacidad es un ciclo de medición, no una división que se hace una sola vez.
Distingue 429 de 503 antes de reintentar
La guía oficial de resolución de problemas asigna significados distintos a 429 RESOURCE_EXHAUSTED y 503 UNAVAILABLE. Ambos pueden ser temporales y admitir backoff exponencial acotado con jitter, pero no apuntan a la misma evidencia ni a la misma solución estable.
| Respuesta | Diagnóstico inicial | Evidencia que revisar | Acción útil | Cuándo parar |
|---|---|---|---|---|
429 RESOURCE_EXHAUSTED | Cuota, frecuencia, RPD, gasto u otro límite de admisión | Cuerpo completo, headers, Retry-After, fila de proyecto/modelo, uso reciente | Encolar, reducir frecuencia o entrada, esperar la ventana correcta, usar la ruta oficial de cuota | Parar reintentos ciegos hasta conocer la dimensión agotada y el reinicio |
503 UNAVAILABLE | Sobrecarga, capacidad o indisponibilidad temporal | Request ID, hora con zona, endpoint o región, modelo, estado del servicio | Backoff acotado, suavizar tráfico, routing global admitido, escalado con evidencia | Parar al gastar el presupuesto de reintentos o si el impacto persiste |
Un 429 provocado por una ráfaga puede desaparecer cuando avance la ventana del minuto. Un 429 por RPD no se resuelve reintentando cada pocos segundos. Una restricción de gasto exige esperar la ventana móvil correcta o actuar sobre la facturación. Si persiste un 503, revisa estado y ruta de capacidad aunque la fila de cuota del proyecto parezca holgada.
Toda política de reintento necesita límites
Una política de producción debe definir, como mínimo:
- qué códigos se pueden reintentar y cuáles obligan a parar;
- si repetir la operación puede duplicar efectos;
- número máximo de intentos y tiempo total máximo;
- backoff exponencial con jitter aleatorio;
- tratamiento de
Retry-Aftercuando exista; - cola o circuit breaker para evitar tormentas sincronizadas;
- métricas separadas para llamadas originales y reintentos;
- paquete de escalado con request ID, modelo exacto, endpoint, hora con zona, respuesta e impacto.
No incluyas claves en ese paquete. Rotarlas como respuesta a una cuota suele conservar el mismo límite del proyecto y, además, oculta qué credencial, servicio y patrón provocaron el incidente. Tampoco distribuyas tráfico entre proyectos para eludir una restricción. Los proyectos separados son correctos cuando representan límites reales de propiedad, facturación, seguridad o entorno.
En el código, el orden de decisión sigue siendo el mismo: identifica el contador agotado y después elige entre reintento, espera, petición de cuota o cambio de capacidad. Añadir backoff sin ese diagnóstico puede aumentar llamadas inútiles frente a RPD o a una ventana de gasto.
Corrige el límite que manda, no el síntoma
La intervención más pequeña y segura depende del contador que se agotó primero:
| Restricción dominante | Control inmediato | Diseño duradero | Atajo incorrecto |
|---|---|---|---|
| RPM | Suavizar ráfagas, limitar concurrencia, encolar | Admission control y presupuestos por workload | Más claves en el mismo proyecto |
| TPM de entrada | Acortar contexto, quitar instrucciones duplicadas, reducir lotes | Cachear prefijos estables y separar trabajos grandes | Contar peticiones sin medir tokens |
| RPD | Eliminar llamadas prescindibles y esperar el reinicio cuando corresponda | Prever volumen diario y evaluar un nivel elegible | Reintentos en bucle corto |
| Ventana de gasto | Reducir trabajo admitido y esperar la ventana aplicable | Alertas y admisión conscientes del coste | Suponer que facturar elimina el límite |
| Priority | Observar el tier devuelto y decidir si se acepta Standard | Reservar Priority para carga sensible a latencia y monitorizarlo | Usarlo como margen universal |
| Batch, tokens o jobs | Distribuir envíos y reducir tamaño | Scheduler asíncrono conforme al contrato actual | Mover trabajo que exige respuesta inmediata |
| Capacidad 503 | Backoff acotado y tráfico más uniforme | Routing global admitido, planificación o Provisioned Throughput | Perseguir cuota sin evidencia de cuota |
La caché aporta más cuando se repite un prefijo grande y estable. Una cola sirve cuando la demanda puede esperar. Batch sirve cuando la respuesta no necesita ser interactiva. Cambiar de modelo solo ayuda si el sustituto está disponible, cumple la calidad necesaria y su fila activa mejora la restricción dominante. Un modelo que aparece en una tabla antigua no constituye un plan de respaldo.
Si solicitas un aumento, aporta proyecto, modelo, distribución del tráfico, dimensión agotada, previsión de crecimiento, mitigaciones ya aplicadas e impacto en el negocio. Esa evidencia permite evaluar la petición mucho mejor que un mensaje que solo diga «necesitamos más RPM».
No traslades límites entre productos Gemini
El nombre Gemini aparece en aplicaciones de consumo, API para desarrolladores, Firebase y Vertex AI, pero sus contratos no son intercambiables.
Gemini Apps usa una asignación de consumidor
Los límites de Gemini Apps dependen del cómputo y pueden variar con el modelo o la función, la complejidad del prompt, los archivos y la longitud de la conversación. A 15 de julio de 2026, la ayuda de Gemini Apps indica que la disponibilidad se actualiza cada cinco horas hasta alcanzar un límite semanal, que puede cambiar con la capacidad y que la hora concreta aparece en Ajustes → Límites de uso.
Esa asignación de consumidor no incrementa RPM, TPM ni RPD de un proyecto de Developer API. Una suscripción a la aplicación y un proyecto API facturado resuelven trabajos diferentes. No copies recuentos de prompts de la aplicación en un plan de capacidad de API.
Firebase AI Logic superpone dos controles
Firebase AI Logic puede añadir un control por usuario delante de la cuota del proveedor. A 15 de julio de 2026, Firebase documenta un valor predeterminado de 100 RPM por usuario. La cuota del proyecto y modelo de Gemini sigue aplicándose detrás.
El techo efectivo es la menor de las capas pertinentes. Si se limita un solo usuario mientras el proyecto tiene margen, revisa el gateway de Firebase. Si fallan muchos usuarios a la vez y la fila de Gemini está agotada, cambiar solo el límite de Firebase no arreglará el problema superior.
Vertex AI utiliza otro contrato de capacidad
Para modelos Gemini recientes en Vertex AI PayGo, Google Cloud describe Dynamic Shared Quota, no una cuota fija universal por proyecto. Un 429 de Vertex puede señalar competencia en un fondo compartido; suavizar tráfico, utilizar un endpoint global adecuado, limitar reintentos o adquirir Provisioned Throughput son opciones propias de esta ruta.
No pegues valores RPM/RPD de Developer API en un plan de Vertex. Si necesitas caudal empresarial predecible, compara el comportamiento observado de PayGo con Provisioned Throughput en lugar de tratar capacidad compartida como garantía fija.
La generación de imágenes añade restricciones específicas de modelo y superficie, como IPM, límites de imágenes en la aplicación o capacidad de Vertex. Si ese es tu caso, utiliza la guía de límites para generar imágenes con Gemini en lugar de extrapolar solo desde Developer API.
Registra el contrato antes de pasar a producción
El registro previo al lanzamiento debería responder a estas preguntas:
- Superficie: ¿Developer API, Gemini Apps, Firebase AI Logic o Vertex AI?
- Propietario: ¿qué proyecto, billing account, cuenta de consumidor o proyecto Firebase lo controla?
- Modelo: ¿qué model ID exacto y qué estado usa la petición?
- Métrica: ¿qué RPM, TPM de entrada, RPD, IPM, TPD, gasto, Batch o Priority se aplica?
- Ventana: ¿cuándo se reinicia o avanza y dónde se volverá a comprobar?
- Forma del tráfico: ¿cuáles son p50/p95 de entrada, latencia p95, factor de ráfaga, volumen diario y tasa de reintentos?
- Admisión: ¿qué cola, límite de concurrencia, presupuesto de tokens y regla de descarte mantienen el objetivo?
- Rama de error: ¿se registran 429 y 503 por separado, con presupuesto de reintentos y regla de parada?
- Carril: ¿se observan Standard, Priority y Batch como contratos distintos?
- Evidencia compartible: ¿pueden guardarse request ID, hora, modelo, proyecto, respuesta e impacto sin exponer credenciales?
Prueba con tamaños parecidos a producción, no con un prompt hello. Mide una ráfaga corta y un periodo sostenido. Confirma que los reintentos aparecen como carga adicional. Configura alertas antes del objetivo operativo elegido, no justo en el techo publicado.
El dashboard más útil no es una pared de cifras por modelo. Durante un incidente debe contestar con rapidez qué superficie posee el fallo, qué contador se agotó primero, qué cambió y qué respuesta es segura.
Preguntas frecuentes
¿Los límites de Gemini API se aplican por clave?
No. En Developer API se aplican por proyecto de Google Cloud. Varias claves del mismo proyecto comparten el mismo fondo de cuota.
¿Gemini API tiene un límite diario?
Algunas filas de proyecto y modelo incluyen RPD o TPD, pero no hay una cifra diaria universal para todos los modelos y niveles. Cuando RPD se aplica, la regla actual lo reinicia a medianoche, hora del Pacífico. Comprueba la fila exacta de AI Studio.
¿Por qué un proyecto de pago aún puede devolver 429?
La facturación puede cambiar la elegibilidad de nivel, pero continúan existiendo RPM, TPM de entrada, RPD, ventanas de gasto, Batch y otras restricciones. Un 429 es una pista para encontrar la dimensión dominante, no una prueba de que falló la facturación.
¿Cuánto tiempo debo esperar después de un 429?
Depende de la ventana agotada. Respeta Retry-After si aparece y contrasta el error con la fila activa. Una espera breve puede aliviar presión por minuto, pero no reinicia RPD ni necesariamente una ventana de gasto.
¿La cuota de Batch API es independiente?
Sí. Batch usa un fondo distinto al de las llamadas interactivas y tiene límites propios de jobs concurrentes, archivos, almacenamiento y tokens en cola. Revisa las condiciones actuales antes de programar volumen de producción.
¿Una suscripción de Gemini Apps aumenta los límites de la API?
No debes suponerlo. Los límites de la aplicación pertenecen a la cuenta y función de consumo. Los de Developer API pertenecen al proyecto de Cloud, modelo, nivel y fila activa de AI Studio.
¿Los límites de Gemini en Vertex AI son iguales a los de Developer API?
No. El tráfico reciente de Vertex AI PayGo usa Dynamic Shared Quota, mientras que Provisioned Throughput representa capacidad adquirida. Diagnostica Vertex con evidencia de Google Cloud, no con una tabla RPM/RPD de Developer API.
¿Varios proyectos de Google Cloud pueden aumentar la capacidad?
Pueden tener propietarios y límites separados cuando representan fronteras reales de entorno, facturación, seguridad u organización. No crees ni rotes proyectos para eludir cuotas. En una arquitectura multi-project legítima, documenta routing, gasto, política de datos y aislamiento de fallos.
¿Qué debo enviar en una petición de soporte por límites?
Incluye la superficie de producto, un identificador de proyecto que sea seguro compartir, modelo exacto, endpoint o región, timestamp con zona horaria, request ID, código y detalles completos, fila activa de límites, distribución reciente de tráfico y tokens, comportamiento de reintentos e impacto. Nunca incluyas la clave de API ni otra credencial.
