La API de Calendar de Google tiene cuotas para garantizar que todos los usuarios la usen de manera justa. Existen tres limitaciones importantes que debes tener en cuenta cuando usas la API de Calendar:
Cuotas de uso de la API: Se aplican por proyecto y por usuario. Para obtener más información, consulta Tipos de cuotas de uso de la API de Calendar.
Límites de uso generales de Calendar de Google: La API de Calendar de Google es un servicio compartido que tiene limitaciones para proteger el rendimiento general del sistema de Google Workspace. Para obtener más información, consulta Evita los límites de uso de Calendar
Límites operacionales: Estos límites se pueden restringir en cualquier momento. Por ejemplo, si intentas escribir en un solo calendario en rápida sucesión.
Cuotas de la API de Calendar
Se aplican dos tipos de cuotas:
Por minuto y por proyecto: Es la cantidad de solicitudes que puede realizar tu proyecto de Google Cloud en un minuto.
Por minuto, por usuario y por proyecto: Es la cantidad de solicitudes que puede realizar un usuario en particular en tu proyecto de Cloud. El objetivo de este límite es ayudarte a garantizar una distribución justa del uso entre tus usuarios.
Las cuotas se calculan por minuto con una ventana deslizante. Un aumento repentino de tráfico que exceda tu cuota por minuto durante un minuto generará un límite de frecuencia durante la siguiente ventana para garantizar que, en promedio, tu uso permanezca dentro de las cuotas.
En la siguiente tabla, se detallan estos límites:
| Tipo de límite de uso | Límite |
|---|---|
| Por minuto y por proyecto | 10,000 solicitudes |
| Por minuto, por usuario y por proyecto | 600 solicitudes |
Límite de facturación diario
Este límite por día y por proyecto define la cantidad máxima de solicitudes que puede usar tu proyecto de Google Cloud en un período de 24 horas antes de que se apliquen los cargos.
El uso por debajo de este umbral no genera cargos adicionales y no se factura tu cuenta de Google Cloud. Los detalles completos de la facturación se compartirán más adelante en 2026 con un aviso de al menos 90 días antes de que entren en vigencia los cambios.
No puedes solicitar un aumento en este límite de umbral diario.
En la siguiente tabla, se detalla el límite:
| Tipo de límite de umbral | Límite |
|---|---|
| Por día y por proyecto | 1,000,000 solicitudes |
Para obtener más información, consulta el modelo estandarizado de Google Workspace para las herramientas de agentes y las APIs.
Resuelve errores de cuota basados en el tiempo
Para todos los errores basados en el tiempo (máximo de N solicitudes por X minutos), te recomendamos que tu código detecte la excepción y use una retirada exponencial truncada para asegurarte de que tus dispositivos no generen una carga excesiva.
La retirada exponencial es una estrategia estándar de manejo de errores para aplicaciones de red. Un algoritmo de retirada exponencial reintenta las solicitudes a través del aumento exponencial de los tiempos de espera entre solicitudes, hasta un tiempo de retirada máximo. Si las solicitudes aún no tienen éxito, es importante que las demoras entre las solicitudes aumenten con el tiempo hasta que la solicitud se realice correctamente.
Algoritmo de ejemplo
Un algoritmo de retirada exponencial vuelve a intentar las solicitudes de forma exponencial, lo que aumenta el tiempo de espera entre los reintentos hasta un tiempo de retirada máximo. Por ejemplo:
- Realiza una solicitud a la API de Calendar de Google.
- Si la solicitud falla, espera 1 +
random_number_millisecondsy vuelve a intentar la solicitud. - Si la solicitud falla, espera 2 +
random_number_millisecondsy vuelve a intentar la solicitud. - Si la solicitud falla, espera 4 +
random_number_millisecondsy vuelve a intentar la solicitud. - Y así sucesivamente, hasta un tiempo de
maximum_backoff. - Continúa con la espera y los reintentos hasta un número máximo de reintentos, pero no aumentes el período de espera entre los reintentos.
Donde:
- El tiempo de espera es
min(((2^n)+random_number_milliseconds), maximum_backoff), connincrementado en 1 para cada iteración (solicitud). random_number_millisecondses un número al azar de milisegundos menor o igual que 1,000. Esto ayuda a evitar los casos en los que muchos clientes se sincronizan por alguna situación y todos realizan el reintento a la vez, lo que hace que se envíen solicitudes sincronizadas en etapas. El valor derandom_number_millisecondsse vuelve a calcular después de cada reintento de solicitud.maximum_backoffsuele ser de 32 o 64 segundos. El valor apropiado depende del caso de uso.
El cliente puede seguir reintentando después de que alcanza el tiempo maximum_backoff.
Después de este punto, los reintentos no necesitan continuar con el aumento del tiempo de retirada. Por
ejemplo, si un cliente usa un tiempo de maximum_backoff de 64 segundos, luego de alcanzar
este valor, el cliente puede volver a intentarlo cada 64 segundos. En algún momento,
se debe evitar que los clientes vuelvan a intentarlo de forma ilimitada.
El tiempo de espera entre los reintentos y la cantidad de reintentos depende del caso práctico y las condiciones de la red.
Precios
Todo uso estándar de la API de Calendar de Google está disponible sin costo adicional. Se prevé que exceder los límites de solicitudes de cuota genere cargos en tu cuenta de facturación de Google Cloud más adelante en 2026. Para obtener más información, consulta el modelo estandarizado de Google Workspace para las APIs y las herramientas de agentes.
Solicita un aumento de la cuota
Según el uso que hagas de los recursos de tu proyecto, es posible que desees solicitar un ajuste de cuota. Las llamadas a la API de una cuenta de servicio se consideran como el uso de una sola cuenta. Solicitar una cuota ajustada no garantiza la aprobación. Las solicitudes de ajuste de cuota que aumenten significativamente el valor de la cuota pueden tardar más en aprobarse.
No todos los proyectos tienen las mismas cuotas. A medida que tu uso de Google Cloud aumenta con el tiempo, es posible que debas aumentar los valores de tu cuota. Si prevés un aumento repentino considerable en el uso, puedes solicitar ajustes en la cuota de forma proactiva en la página Cuotas y límites del sistema de la consola de Google Cloud.
Para obtener más información, consulta los siguientes recursos:
- Acerca de los ajustes de cuota
- Visualiza el uso y los límites de la cuota
- Solicita un límite de cuota más alto
Solucionar problemas
Si se excede alguna de las cuotas, se limita la frecuencia y se recibe un 403
usageLimits
código de estado o un 429
usageLimits
código de estado en respuesta a tus consultas.
Si eso ocurre, puedes probar lo siguiente:
Asegúrate de seguir todas las prácticas recomendadas: usa la retirada exponencial exponencial, aleatoriza los patrones de tráfico, y usa notificaciones push.
Si tu proyecto está creciendo y tienes más usuarios, puedes solicitar un aumento de la cuota.
Si alcanzas los límites de cuota por usuario, puedes hacer lo siguiente:
Si usas una cuenta de servicio, asigna la carga a los usuarios o divídela entre varias cuentas de servicio.
Si bien puedes solicitar un aumento en la cuota por usuario, en general, no se recomienda aumentarla por encima del valor predeterminado, ya que tu aplicación puede comenzar a alcanzar otros tipos de límites, por ejemplo, límites de uso generales de Calendar o límites operacionales.
Para probar los límites de cuota, registra un proyecto de prueba independiente que tenga una configuración similar a la de tu proyecto de producción. Para obtener más información, consulta Prueba el manejo de límites de cuota.
Aleatoriza los patrones de tráfico
Los clientes de Calendar son propensos a patrones de tráfico irregulares causados por varios clientes que realizan operaciones al mismo tiempo. Por ejemplo, una práctica inadecuada común para un cliente de Calendar es realizar una sincronización completa a la medianoche. Esto casi con certeza haría que se exceda tu cuota por minuto y generaría límites de frecuencia y retiradas.
Para evitar esto, asegúrate de que tu tráfico se distribuya durante todo el día siempre que sea posible. Si tu cliente necesita realizar una sincronización diaria, haz que determine una hora aleatoria (diferente para cada cliente). Si necesitas realizar una operación de forma regular, varía el intervalo +/- 25%. Esto distribuirá el tráfico de manera más uniforme y proporcionará una experiencia del usuario mucho mejor.
Usar notificaciones push
Un caso de uso común es realizar una acción cada vez que cambia algo en el calendario del usuario. Un antipatrón aquí es sondear repetidamente cada calendario de interés. Esto agotará rápidamente toda tu cuota. Por ejemplo, si tu aplicación tiene 5,000 usuarios y sondea el calendario de cada usuario una vez por minuto, esto requiere una cuota por minuto de al menos 5,000, incluso antes de que se realice cualquier trabajo.
Las aplicaciones del servidor pueden registrarse para recibir notificaciones push, lo que nos permite notificarte cuando sucede algo de interés. Estas requieren más trabajo para configurarse, pero permiten un uso mucho más eficiente de tu cuota y proporcionan una mejor experiencia del usuario. Asegúrate de especificar el eventType para el que deseas recibir notificaciones. Para obtener más información, consulta Notificaciones
push.
Asignación adecuada con cuentas de servicio
Si tu aplicación realiza solicitudes con la delegación en todo el dominio, de forma predeterminada, se cobra a la cuenta de servicio con respecto a las cuotas "por minuto, por usuario y por proyecto", y no al usuario que suplantas. Esto significa que es probable que la cuenta de servicio se quede sin cuota y se limite la frecuencia, incluso si opera en los calendarios de varios usuarios.
Para evitar esto, usa el parámetro de URL quotaUser (o el encabezado HTTP x-goog-quota-user) para indicar a qué usuario se le cobra. Esto solo se usa para los cálculos de cuota. Para obtener más información, consulta Cómo limitar las solicitudes por
usuario.
Prueba el manejo de límites de cuota
Para asegurarte de que tu aplicación pueda controlar correctamente el alcance de los límites de cuota en la práctica (por ejemplo, a través de reintentos con retirada exponencial y retirada) y minimizar cualquier posible interrupción para tus usuarios, te recomendamos que pruebes tu situación en un entorno real.
Para realizar pruebas sin interferir con el uso real de tu aplicación, te recomendamos que registres un proyecto de prueba independiente en la consola de Google Cloud y, luego, configures la pantalla de consentimiento de OAuth de una manera similar a la de tu proyecto de producción. Luego, puedes establecer límites de cuota bajos para este proyecto y observar el comportamiento de tu aplicación.