Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Límites de uso

La API de Calendario de Google tiene cuotas para garantizar que todos los usuarios la utilicen de forma justa. Hay 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 del Calendario de Google: La API de Calendario 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 del Calendario.
Límites operativos: Estos límites se pueden restringir en cualquier momento. Por ejemplo, si intentas escribir en un solo calendario en una sucesión rápida.

Cuotas de la API de Calendar

Se aplican dos tipos de cuotas:

Por minuto por proyecto: Es la cantidad de solicitudes que tu proyecto de Google Cloud puede realizar en un minuto.
Por minuto, por usuario y por proyecto: Es la cantidad de solicitudes que un usuario en particular puede realizar en tu proyecto de Cloud. Este límite tiene como objetivo ayudarte a garantizar una distribución justa del uso entre tus usuarios.

Las cuotas se calculan por minuto con una ventana deslizante. Un aumento rápido del tráfico que supere tu cuota por minuto durante un minuto generará un límite de frecuencia durante la siguiente ventana para garantizar que, en promedio, tu uso se mantenga dentro de las cuotas.

En la siguiente tabla, se detallan estos límites:

Tipo de límite de uso	Límite
Por minuto, por proyecto	10,000 solicitudes
Por minuto por usuario 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 cargos.

El uso que no supere este umbral no generará cargos adicionales y no se facturará a tu cuenta de Google Cloud. Los detalles completos de la facturación se compartirán más adelante en 2026 con, al menos, 90 días de anticipación antes de que se apliquen los cambios.

No puedes solicitar un aumento de 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 de solicitudes

Para obtener más información, consulta Modelo estandarizado de Google Workspace para herramientas y APIs de agentes.

Cómo resolver errores de cuota basados en el tiempo

Para todos los errores basados en el tiempo (un 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 siguen sin tener é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:

Realizar una solicitud a la API de Calendario de Google
Si la solicitud falla, espera 1 + random_number_milliseconds y vuelve a intentar la solicitud.
Si la solicitud falla, espera 2 + random_number_milliseconds y vuelve a intentar la solicitud.
Si la solicitud falla, espera 4 + random_number_milliseconds y vuelve a intentar la solicitud.
Y así sucesivamente, hasta un tiempo de maximum_backoff.
Sigue con la espera y los reintentos hasta llegar a una cantidad máxima, 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), n se incrementa en 1 para cada iteración (solicitud).
random_number_milliseconds es un número al azar de milisegundos menor o igual que 1,000. Esto ayuda a evitar casos en los que muchos clientes se sincronizan por alguna situación y todos vuelven a intentarlo a la vez, lo que envía solicitudes en oleadas sincronizadas. El valor de random_number_milliseconds se vuelve a calcular después de cada reintento de solicitud.
maximum_backoff suele 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 de 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, después 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 el uso estándar del Calendario de Google API está disponible sin costo adicional. Se prevé que, más adelante en 2026, se generen cargos en tu cuenta de facturación de Google Cloud si se superan los límites de solicitudes de cuota. Para obtener más información, consulta el modelo estandarizado de Google Workspace para herramientas y APIs 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. Se considera que las llamadas a la API que realiza una cuenta de servicio usan una sola cuenta. Solicitar un ajuste de cuota no garantiza la aprobación. Las solicitudes de ajuste de cuota que aumentarían 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 tus valores de cuota deban aumentar. Si prevés un aumento 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:

Solucionar problemas

Si se supera alguna de las cuotas, se aplicará un límite de frecuencia y recibirás un código de estado 403 usageLimits o un código de estado 429 usageLimits en respuesta a tus consultas.

Si esto sucede, puedes probar lo siguiente:

Asegúrate de seguir todas las prácticas recomendadas: usa la retirada 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 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 generales de uso del calendario o límites operativos.
Para probar tus límites de cuota, registra un proyecto independiente solo para pruebas 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 Calendario son propensos a patrones de tráfico con aumentos repentinos causados por varios clientes que realizan operaciones al mismo tiempo. Por ejemplo, una mala práctica común para un cliente de Calendario es realizar una sincronización completa a la medianoche. Esto casi con seguridad provocaría que se excediera 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 a lo largo del día siempre que sea posible. Si tu cliente necesita realizar una sincronización diaria, pídele que determine una hora aleatoria (diferente para cada cliente). Si necesitas realizar una operación de forma regular, varía el intervalo en un +/-25%. Esto distribuirá el tráfico de manera más uniforme y proporcionará una experiencia del usuario mucho mejor.

Usa 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á muy rápido toda tu cuota. Por ejemplo, si tu aplicación tiene 5,000 usuarios y sondea el calendario de cada usuario una vez por minuto, se 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 ocurre algo de interés. Estas requieren más trabajo de configuración, 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 de todo el dominio, de forma predeterminada, se cobra a la cuenta de servicio en relación con las cuotas "por minuto por usuario 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 su frecuencia, aunque esté operando en los calendarios de varios usuarios.

Para evitarlo, puedes usar el parámetro de URL quotaUser (o el encabezado HTTP x-goog-quota-user) para especificar una cadena arbitraria (de hasta 40 caracteres) que identifique de forma inequívoca a cada usuario. La API de Calendar usa este valor solo para los cálculos de cuota.

Para usar quotaUser con el objetivo de aplicar límites de frecuencia por usuario en distintos usuarios, tus solicitudes deben cumplir con los siguientes requisitos:

Incluye una clave de API con restricción de IP: Pasa una clave de API en el parámetro de consulta key y configúrala con restricciones de dirección IP que especifiquen las direcciones IP públicas de tus servidores de backend. Si omites la clave de API o no configuras las restricciones de dirección IP, la API de Calendar ignora quotaUser y cobra la cuota a la cuenta autenticada (como la cuenta de servicio).
Omite el encabezado X-Goog-User-Project: No envíes un encabezado HTTP X-Goog-User-Project en las solicitudes que usen quotaUser. Proporcionar un proyecto de usuario anula la clave de API para la atribución de cuota, por lo que la API de Calendar ignora quotaUser.

Para obtener más información, consulta Limita las solicitudes por usuario.

Prueba el manejo del límite de cuota

Para asegurarte de que tu aplicación pueda controlar de forma correcta el alcance de los límites de cuota en la práctica (por ejemplo, a través de reintentos con retirada exponencial) 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 en el uso real de la aplicación, te recomendamos que registres un proyecto independiente solo para pruebas en la consola de Google Cloud y, luego, configures la pantalla de consentimiento de OAuth de manera similar a tu proyecto de producción. Luego, puedes establecer límites de cuota artificialmente bajos para este proyecto y observar el comportamiento de tu aplicación.

Cuotas del servidor de MCP de Calendario

El servidor de MCP de Calendario usa una métrica de asignación de costos de consultas. En las siguientes tablas, se detalla el costo de consulta para cada método del servidor de MCP del Calendario por sección:

Cuotas de MCP de Calendario