Límites de uso

La API de Gmail está sujeta a límites de uso que restringen la frecuencia con la que se pueden llamar a los métodos de la API. Los límites se definen en términos de unidades de cuota, una unidad de medida abstracta que representa el uso de recursos de Gmail.

Cuotas de la API de Gmail

Se aplican dos tipos de cuotas:

  • Por minuto y por proyecto: Es la cantidad de unidades de cuota que puede usar tu proyecto de Google Cloud en un minuto.

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

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

Tipo de límite de uso Límite
Por minuto y por proyecto 1,200,000 unidades de cuota
Por minuto, por usuario y por proyecto 6,000 unidades de cuota

Para obtener información sobre cómo manejar los errores de límite, consulta Cómo resolver errores.

Límite de facturación diario

Este límite por día y por proyecto define la cantidad máxima de unidades de cuota 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 límite no genera cargos adicionales, y tu cuenta de Google Cloud no se factura. 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 diario.

En la siguiente tabla, se detalla el límite:

Tipo de límite Límite
Por día y por proyecto 80,000,000 unidades de cuota

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

Uso de cuota por método

La cantidad de unidades de cuota consumidas por solicitud varía según el método llamado. En la siguiente tabla, se describe el uso de unidades de cuota por método:

Método Unidades de cuota
drafts.create 10
drafts.delete 10
drafts.get 20
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 20
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 40
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Cuando se usa la API de Gmail, también hay un límite de 500 destinatarios por mensaje de correo electrónico.

Cómo resolver 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:

  1. Realiza una solicitud a la API de Gmail.
  2. Si la solicitud falla, espera 1 + random_number_milliseconds y vuelve a intentar la solicitud.
  3. Si la solicitud falla, espera 2 + random_number_milliseconds y vuelve a intentar la solicitud.
  4. Si la solicitud falla, espera 4 + random_number_milliseconds y vuelve a intentar la solicitud.
  5. Y así sucesivamente, hasta un tiempo de maximum_backoff.
  6. 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), con n incrementado 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 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 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 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 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 el uso estándar de la API de Gmail está disponible sin costo adicional. Se planea que superar los límites de solicitud 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 realizadas por 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 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: