Limites de uso

A API Gmail está sujeita a limites de uso que restringem a taxa em que os métodos da API podem ser chamados. Os limites são definidos em termos de unidades de cota, uma unidade abstrata de medição que representa o uso de recursos do Gmail. Há dois limites de uso aplicados simultaneamente: um limite de taxa por projeto e um limite de taxa por usuário.

A tabela a seguir detalha esses limites:

Tipo de limite de uso Limite Código do erro
Limite de taxa por projeto 1.200.000 unidades de cota por minuto rateLimitExceeded
Limite de taxa por usuário 15.000 unidades de cota por minuto por usuário userRateLimitExceeded

Para informações sobre como lidar com erros de limite, consulte Resolver erros.

Uso de cota por método

O número de unidades de cota consumidas por uma solicitação varia de acordo com o método chamado. A tabela a seguir descreve o uso de unidades de cota por método:

Método Unidades de cota
drafts.create 10
drafts.delete 10
drafts.get 5
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 5
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 5
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 5
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 10
threads.list 10
threads.modify 10
threads.trash 10
threads.untrash 10
watch 100

Ao usar a API Gmail, também há um limite de 500 destinatários por mensagem de e-mail.

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:

  1. Faça uma solicitação para a API Gmail.
  2. Se a solicitação falhar, aguarde 1 + random_number_milliseconds e tente de novo.
  3. Se a solicitação falhar, aguarde 2 + random_number_milliseconds segundos e tente de novo.
  4. Se a solicitação falhar, aguarde 4 + random_number_milliseconds segundos e tente de novo.
  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, sem aumentar o tempo 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 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 da API Gmail está disponível sem custo financeiro adicional. Exceder os limites de solicitação de cota não gera cobranças extras, e sua conta não é faturada.

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 usando 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 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" no console do Google Cloud.

Para saber mais, consulte os seguintes recursos: