Limites de uso

A API Google Sheets é um serviço compartilhado, e aplicamos cotas e limitações para proteger o desempenho geral do sistema do Google Workspace para todos os usuários.

Limites de cota

Embora a API Sheets não tenha limites de tamanho rígidos para uma solicitação de API, os usuários podem encontrar limites de diferentes componentes de processamento não controlados pelo Google Sheets. Para acelerar as solicitações, recomendamos um payload máximo de 2 MB.

A API Sheets tem cotas por minuto, e elas são reabastecidas a cada minuto. Por exemplo, há um limite de solicitação de leitura de 300 por minuto por projeto. Se o app enviar 350 solicitações em um minuto, as 50 solicitações extras vão exceder a cota e gerar uma resposta de código de status HTTP 429: Too many requests. Se isso acontecer, use um algoritmo de espera exponencial. Após 1 minuto, você poderá executar solicitações novamente.

A tabela a seguir detalha os limites de solicitação:

Cotas
Solicitações de leitura
Por minuto em cada projeto 300
Por minuto por usuário por projeto 60
Solicitações de gravação
Por minuto em cada projeto 300
Por minuto por usuário por projeto 60

Para mais detalhes sobre os limites de arquivos, consulte Arquivos que podem ser armazenados no Google Drive.

Comportamento e limitações

Ao trabalhar com ((sheets_api_short)), observe o seguinte comportamento e limitações que afetam suas cotas:

  • As solicitações de leitura são chamadas para qualquer método que recupere dados de uma planilha, como get ou search. As solicitações de gravação são chamadas para qualquer método que mude uma planilha, como update, clear ou copyTo.

  • Os usuários podem enviar várias solicitações ao mesmo tempo, desde que estejam dentro do limite de cota. Cada solicitação em lote, incluindo qualquer sub-solicitação, é contabilizada como uma solicitação de API para o limite de uso.

  • Todas as solicitações do Sheets são aplicadas atomicamente. Ou seja, se alguma solicitação não for válida, toda a atualização vai falhar e nenhuma das mudanças (possivelmente dependentes) será aplicada.

  • Há um limite máximo de tempo para processar uma solicitação de API. Quando o Sheets processa uma solicitação por mais de 180 segundos, ela retorna um erro de tempo limite.

  • Desde que você permaneça dentro das cotas por minuto, não há limite para o número de solicitações que podem ser feitas por dia.

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 o código detecte a exceção e use uma espera exponencial truncada para garantir que os 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 retirada exponencial repete solicitações exponencialmente, aumentando o tempo de espera entre novas tentativas até um tempo máximo de retirada. Exemplo:

  1. Faça uma solicitação para a API Google Sheets.
  2. Se a solicitação falhar, aguarde 1 + random_number_milliseconds e tente novamente a solicitação.
  3. Se a solicitação falhar, aguarde 2 + random_number_milliseconds e tente novamente a solicitação.
  4. Se a solicitação falhar, aguarde 4 + random_number_milliseconds e tente novamente a solicitação.
  5. E assim por diante, até um tempo maximum_backoff.
  6. 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 ao mesmo tempo, enviando solicitações em ondas sincronizadas. O valor de random_number_milliseconds é recalculado após cada nova tentativa de solicitação.
  • maximum_backoff costuma 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 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 Sheets está disponível sem custo extra. O excesso dos 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 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. Solicitar uma cota ajustada não garante a aprovação. As solicitações de ajuste de cota que aumentam 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: