O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Limites de uso

A API Google Calendar tem cotas para garantir que ela seja usada de forma justa por todos os usuários. Considere três limitações importantes ao usar a API Calendar:

Cotas de uso da API: aplicadas por projeto e por usuário. Para mais informações, consulte Tipos de cotas de uso da API Calendar.
Limites gerais de uso do Calendar: a API Calendar é um serviço compartilhado que tem limitações para proteger o desempenho geral do sistema do Google Workspace. Para mais informações, consulte Evitar limites de uso do Agenda.
Limites operacionais: esses limites podem ser aplicados a qualquer momento. Por exemplo, os limites podem ser aplicados se você tentar gravar em uma única agenda em rápida sucessão.

Cotas da API Calendar

Dois tipos de cotas são aplicados:

Por minuto por projeto:é o número de solicitações que seu projeto do Google Cloud pode fazer em um minuto.
Por minuto por usuário por projeto:é o número de solicitações que um usuário específico pode fazer no seu projeto na nuvem. Esse limite ajuda a garantir uma distribuição justa do uso entre os usuários.

As cotas são calculadas por minuto usando uma janela deslizante. Um pico rápido de tráfego que exceda sua cota por minuto resulta em limitação de taxa durante a próxima janela para garantir que, em média, seu uso permaneça dentro das cotas.

A tabela a seguir detalha esses limites:

Tipo de limite de uso	Limite
Por minuto por projeto	10.000 solicitações
Por minuto por usuário por projeto	600 solicitações

Limite diário de faturamento

Esse limite por dia por projeto define o número máximo de solicitações que seu projeto na nuvem pode usar em um período de 24 horas antes que as cobranças sejam aplicadas.

O uso abaixo desse limite não gera cobranças extras, e sua conta do Google Cloud não é faturada. Os detalhes completos do faturamento serão compartilhados mais tarde em 2026, com pelo menos 90 dias de antecedência antes que as mudanças entrem em vigor.

Não é possível solicitar um aumento para esse limite diário.

A tabela a seguir detalha o limite:

Tipo de limite	Limite
Por dia por projeto	1.000.000 de solicitações

Para mais informações, consulte Modelo padronizado do Google Workspace para ferramentas de agente e APIs.

Resolver erros de cota com base no tempo

Para todos os erros com base no tempo (máximo de N solicitações por X minutos), recomendamos que seu código detecte a exceção e use uma espera exponencial truncada para garantir que seus dispositivos não gerem carga excessiva.

A espera exponencial é uma estratégia padrão de tratamento de erros para aplicativos de rede. Um algoritmo de espera exponencial repete solicitações usando tempos de espera exponencialmente crescentes entre as solicitações, até um tempo máximo de espera. Se as solicitações ainda não forem bem-sucedidas, é importante que os atrasos entre as solicitações aumentem com o tempo até que a solicitação seja bem-sucedida.

Exemplo de algoritmo

Um algoritmo de espera exponencial repete solicitações exponencialmente, aumentando o tempo de espera entre novas tentativas até um tempo máximo de espera. Exemplo:

Faça uma solicitação para a API Google Calendar.
Se a solicitação falhar, aguarde 1 + random_number_milliseconds e tente novamente a solicitação.
Se a solicitação falhar, aguarde 2 + random_number_milliseconds e tente novamente a solicitação.
Se a solicitação falhar, aguarde 4 + random_number_milliseconds e tente novamente a solicitação.
E assim por diante, até um tempo maximum_backoff.
Continue aguardando e tentando novamente até um número máximo de novas tentativas, mas não aumente o período de espera entre elas.

em que:

O tempo de espera é min(((2^n)+random_number_milliseconds), maximum_backoff), com n incrementado em 1 para cada iteração (solicitação).
random_number_milliseconds é um número aleatório de milissegundos menor ou igual a 1.000. Isso ajuda a evitar casos em que muitos clientes são sincronizados por alguma situação e todos tentam novamente de uma só vez, enviando solicitações em ondas sincronizadas. O valor de random_number_milliseconds é recalculado após cada nova tentativa.
maximum_backoff costuma ser 32 ou 64 segundos. O valor apropriado depende do caso de uso.

O cliente pode continuar tentando novamente depois de maximum_backoff. As novas tentativas após esse ponto não precisam continuar aumentando o tempo de espera. Por exemplo, se um cliente usar um tempo maximum_backoff de 64 segundos, depois de atingir este valor, o cliente poderá tentar novamente a cada 64 segundos. Em algum momento, os clientes precisam ser impedidos de tentar novamente indefinidamente.

O tempo de espera entre novas tentativas e o número de novas tentativas dependem do seu caso de uso e das condições de rede.

Preços

Todo o uso padrão da API Google Calendar está disponível sem custo adicional. O excesso dos limites de solicitação de cota está planejado para gerar cobranças na sua conta de faturamento do Google Cloud mais tarde em 2026. Para mais informações, consulte Modelo padronizado do Google Workspace para ferramentas de agente e APIs.

Solicitar aumento de cota

Dependendo do uso de recursos do seu projeto, talvez você queira solicitar um ajuste de cota. As chamadas de API por uma conta de serviço são consideradas como o uso de uma única conta. A solicitação de uma cota ajustada não garante a aprovação. As solicitações de ajuste de cota que aumentariam significativamente o valor da cota podem levar mais tempo para serem aprovadas.

Nem todos os projetos têm as mesmas cotas. À medida que você usa o Google Cloud com mais frequência, os valores de cota podem precisar aumentar. Caso espere um aumento de uso significativo, solicite o ajuste das cotas na página Cotas e limites do sistema no console do Google Cloud.

Para saber mais, consulte os seguintes recursos:

Resolver problemas

Se uma das cotas for excedida, você será limitado e receberá um 403 usageLimits código de status ou um 429 usageLimits código de status em resposta às suas consultas.

Se isso acontecer, tente o seguinte:

Siga todas as práticas recomendadas: use a espera exponencial exponencial, randomize os padrões de tráfego, e use notificações push.
Se o projeto estiver crescendo e você tiver mais usuários, solicite um aumento de cota.
Se você atingir os limites de cota por usuário, faça o seguinte:
- Se você usa uma conta de serviço, aloque a carga para os usuários ou divida-a entre várias contas de serviço.
- Embora seja possível solicitar um aumento na cota por usuário, em geral, não recomendamos aumentá-la acima do valor padrão, porque seu aplicativo pode atingir outros tipos de limites, por exemplo, limites gerais de uso do Agenda ou limites operacionais.
Teste os limites de cota registrando um projeto de teste separado que tenha uma configuração semelhante ao seu projeto de produção. Para mais informações, consulte Testar o tratamento de limites de cota.

Randomizar padrões de tráfego

Os clientes do Calendar estão sujeitos a padrões de tráfego instáveis causados por vários clientes que realizam operações ao mesmo tempo. Por exemplo, uma prática ruim comum para um cliente do Calendar é realizar uma sincronização completa à meia-noite. Isso geralmente excede sua cota por minuto e causa limitação de taxa e espera.

Para evitar isso, distribua o tráfego ao longo do dia sempre que possível. Se o cliente precisar fazer uma sincronização diária, peça para ele determinar um horário aleatório (diferente para cada cliente). Se você precisar realizar uma operação regularmente, varie o intervalo em ±25%. Isso distribui o tráfego de maneira mais uniforme e oferece uma melhor experiência do usuário.

Usar notificações push

Um caso de uso comum é realizar uma ação sempre que algo mudar na agenda do usuário. Um antipadrão aqui é consultar repetidamente todas as agendas de interesse. Isso esgota rapidamente sua cota. Por exemplo, se o aplicativo tiver 5.000 usuários e consultar a agenda de cada usuário uma vez por minuto, isso exigirá uma cota por minuto de pelo menos 5.000, mesmo antes de qualquer trabalho ser feito.

Os aplicativos do lado do servidor podem se registrar para receber notificações push, o que permite que o Calendar notifique você quando algo de interesse acontecer. Esses aplicativos exigem mais trabalho para serem configurados, mas permitem que você use a cota de maneira mais eficiente e ofereça uma melhor experiência do usuário. Especifique o eventType para o qual você quer receber notificações. Para mais informações, consulte Notificações push.

Alocação adequada com contas de serviço

Se o aplicativo realizar solicitações usando delegação em todo o domínio, por padrão, a conta de serviço será cobrada em relação às cotas "por minuto por usuário por projeto", e não o usuário que você está representando. Isso significa que a conta de serviço provavelmente vai esgotar a cota e será limitada, mesmo que opere em agendas de vários usuários.

Para evitar isso, use o parâmetro de URL quotaUser (ou o cabeçalho HTTP x-goog-quota-user) para indicar qual usuário será cobrado. O Google usa esse parâmetro apenas para cálculos de cota. Para mais informações, consulte Limitar solicitações por usuário.

Testar o tratamento de limites de cota

Para garantir que seu aplicativo trate corretamente o alcance dos limites de cota na prática (por exemplo, por novas tentativas com espera exponencial exponencial) e para minimizar possíveis interrupções para os usuários, teste o aplicativo em um ambiente realista.

Para testar sem interferir no uso real do aplicativo, registre um projeto de teste separado no console do Google Cloud e, em seguida, configure a tela de consentimento do OAuth de maneira semelhante ao seu projeto de produção. Em seguida, defina limites de cota artificialmente baixos para esse projeto e observe o comportamento do aplicativo.

Cotas do servidor MCP do Calendar

O servidor MCP do Calendar usa uma métrica de alocação de custo de consulta. As tabelas a seguir detalham o custo da consulta para cada método do servidor MCP do Calendar por seção:

Cotas do MCP do Calendar