A API Google Agenda tem cotas para garantir que ela seja usada de forma justa por todos os usuários. Há três limitações importantes a serem consideradas ao usar a API Calendar:
Cotas de uso da API: aplicadas por projeto e por usuário. Para mais informações, consulte Tipos de quota de uso da API Calendar.
Limites gerais de uso do Google Agenda: a API Google 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 Google Agenda.
Limites operacionais: podem ser limitados a qualquer momento. Por exemplo, 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 e por projeto:é o número de solicitações que um usuário específico pode fazer no seu projeto na nuvem. O objetivo desse limite é ajudar você 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 durante um minuto vai resultar 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 em cada projeto | 10.000 solicitações |
| Por minuto, por usuário e por projeto | 600 solicitações |
Limite de faturamento diário
Esse limite por dia por projeto define o número máximo de solicitações que seu projeto do Google Cloud pode usar em um período de 24 horas antes da cobrança.
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 ainda 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 nesse limite diário.
A tabela a seguir detalha o limite:
| Tipo de limite de limite | Limite |
|---|---|
| Por dia e 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 baseados em tempo (máximo de N solicitações por X minutos), recomendamos que seu código capture 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 elas 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_millisecondse tente de novo. - Se a solicitação falhar, aguarde 2 +
random_number_millisecondssegundos e tente de novo. - Se a solicitação falhar, aguarde 4 +
random_number_millisecondssegundos e tente de novo. - E assim por diante, até um tempo
maximum_backoff. - Continue aguardando e tentando novamente até um número máximo de novas tentativas, sem aumentar o tempo de espera entre elas.
em que:
- O tempo de espera é
min(((2^n)+random_number_milliseconds), maximum_backoff), comnincrementado 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 ao mesmo tempo, enviando solicitações em ondas sincronizadas. O valor derandom_number_millisecondsé recalculado após cada nova tentativa de solicitação.maximum_backoffcostuma ser 32 ou 64 segundos. O valor adequado 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
esse valor, ele poderá tentar novamente a cada 64 segundos. Em algum momento,
os clientes precisam ser impedidos de tentar novamente infinitas vezes.
O tempo de espera entre novas tentativas e o número de novas tentativas depende do seu caso de uso e das condições da rede.
Preços
Todo uso padrão da API Google Agenda está disponível sem custo financeiro adicional. Exceder os limites de solicitação de cota vai gerar cobranças na sua conta de faturamento do Google Cloud no final de 2026. Para mais informações, consulte Modelo padronizado do Google Workspace para ferramentas e APIs de agentes.
Solicitar aumento de cota
Dependendo do uso de recursos do seu projeto, talvez seja necessário solicitar um ajuste de cota. As chamadas de API feitas por uma conta de serviço são consideradas como se usassem uma única conta. Solicitar 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 mais o Google Cloud, os valores das cotas 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ê vai receber um código de status 403
usageLimits ou 429
usageLimits em resposta às suas consultas.
Se isso acontecer, tente o seguinte:
Siga todas as práticas recomendadas: use espera exponencial, aleatorize 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, poderá fazer o seguinte:
Se você usa uma conta de serviço, aloca a carga para usuários ou divide entre várias contas de serviço.
Embora seja possível solicitar um aumento na cota por usuário, em geral, não é recomendável aumentar acima do valor padrão, já que o aplicativo pode começar a atingir outros tipos de limites, por exemplo, limites gerais de uso do calendário ou limites operacionais.
Teste seus limites de cota registrando um projeto separado somente para testes com uma configuração semelhante ao seu projeto de produção. Para mais informações, consulte Como testar o processamento de limites de cota.
Tornar padrões de tráfego aleatórios
Os clientes de agenda estão sujeitos a padrões de tráfego irregulares causados por vários clientes realizando operações ao mesmo tempo. Por exemplo, uma prática ruim comum para um cliente do Google Agenda é realizar uma sincronização completa à meia-noite. Isso quase certamente vai fazer você exceder sua cota por minuto e resultar em limitação de taxa e espera.
Para evitar isso, distribua seu 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 vai distribuir o tráfego de maneira mais uniforme e proporcionar uma experiência do usuário muito melhor.
Usar notificações push
Um caso de uso comum é realizar uma ação sempre que algo muda no calendário do usuário. Um antipadrão aqui é consultar repetidamente todos os calendários de interesse. Isso vai consumir toda a sua cota muito rapidamente. Por exemplo, se seu aplicativo tiver 5.000 usuários e sondar o calendário de cada um deles 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 nos permite
avisar você quando algo de interesse acontece. Elas exigem mais trabalho para serem configuradas, mas permitem um uso muito mais eficiente da sua cota e proporcionam uma melhor experiência do usuário. Especifique o eventType para receber notificações. Para mais informações, consulte Notificações
push.
Alocação adequada com contas de serviço
Se o aplicativo estiver fazendo solicitações usando a 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 ficar sem cota e será limitada por taxa, mesmo que esteja operando em várias agendas de 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. Isso é usado apenas para cálculos de cota. Para mais informações, consulte Limitar solicitações por
usuário.
Testar o processamento de limite de cota
Para garantir que seu aplicativo possa lidar normalmente com o alcance dos limites de cota na prática (por exemplo, por tentativas com retirada exponencial) e minimizar possíveis problemas para seus usuários, recomendamos testar seu cenário em um ambiente real.
Para testar sem interferir no uso real do aplicativo, recomendamos registrar um projeto separado apenas para testes no console do Google Cloud e configurar a tela de permissão OAuth de maneira semelhante ao projeto de produção. Em seguida, defina limites de cota artificialmente baixos para esse projeto e observe o comportamento do aplicativo.