Limites e cotas de APIs

A API Google Ads impõe limites às operações da API, como o número de operações que podem ser enviadas em uma única solicitação de mutação. A tabela a seguir resume alguns dos limites e cotas importantes.

Tipo de solicitação, limitação e código de erro
Operações com acesso básico	15.000 operações de API por dia	RESOURCE_EXHAUSTED
Solicitações de modificação	10.000 operações por solicitação	TOO_MANY_MUTATE_OPERATIONS
Solicitações de planejamento de serviço	1 QPS	RESOURCE_EXHAUSTED
Solicitações do serviço de upload de conversões	2.000 conversões por solicitação	TOO_MANY_CONVERSIONS_IN_REQUEST
Solicitações de serviço de faturamento e orçamento da conta	Uma operação por solicitação de mutação	TOO_MANY_MUTATE_OPERATIONS

Limites diários de operação da API

Os limites diários de uso da API são baseados no número de operações de API feitas por token de desenvolvedor. As operações da API são a soma total de operações de mutação e solicitações de recebimento. Os limites para operações diárias de API dependem do nível de acesso do token do desenvolvedor. O guia "Níveis de acesso e uso permitido" descreve os limites específicos de operação da API para cada nível de acesso.

As solicitações que violam esses limites são rejeitadas com o erro: RESOURCE_EXHAUSTED.

Limitações do gRPC

Todas as bibliotecas de cliente da API Google Ads usam o gRPC para gerar solicitações e respostas. Por padrão, o gRPC tem um tamanho de mensagem de 4 MB, mas nossas bibliotecas de cliente definem o tamanho máximo de mensagem como 64 MB para aumentar a eficiência.

As respostas não podem exceder esse limite. Por exemplo, uma solicitação de pesquisa que inclui muitos campos pode gerar uma resposta com mais de 64 MB. Para evitar esse limite, reduza o número de campos selecionados ou use o streaming. Para mutações, envie menos operações por solicitação.

As solicitações que violam essa limitação não geram um GoogleAdsError, mas geram um erro gRPC 429 Resource Exhausted. Consulte a lista de códigos e mensagens de erro do gRPC.

Solicitações de modificação

Além de contar para a cota de operações diárias do usuário, uma solicitação de mutação não pode conter mais de 10.000 operações por solicitação.

As solicitações que violam essa limitação são rejeitadas com o erro: TOO_MANY_MUTATE_OPERATIONS.

Confira a seguir outros limites e considerações para serviços e tipos de solicitação específicos.

Solicitações de pesquisa

Uma solicitação Search ou SearchStream é contabilizada como uma operação na cota de operações diárias do usuário. Uma solicitação SearchStream é contabilizada como uma operação de API, independente do número de lotes.

Solicitações paginadas

As solicitações paginadas (por exemplo, as que contêm um next_page_token válido) não são contabilizadas na cota de operação diária de um usuário. No entanto, as solicitações de paginação que contêm um token de página expirado ou inválido vão gerar uma exceção e contar para a cota de operação diária.

Para mais detalhes sobre a paginação, consulte Como fazer a paginação de resultados.

Outros tipos de solicitações

Uma solicitação que não seja Get, Mutate, Search ou SearchStream é contabilizada como uma operação na cota diária de operações do usuário.

Confira alguns exemplos de solicitações:

• BatchJobService.ListMutateJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

Solicitações que retornam exceções de API

As solicitações rejeitadas com um GoogleAdsFailure ainda são contabilizadas na cota de operação diária do usuário.

As solicitações que falham, mas não retornam uma GoogleAdsFailure, como um erro no nível da rede, não são contabilizadas na cota de operação diária do usuário, já que as solicitações nunca chegam ao serviço. Um exemplo disso é uma falha na conectividade de rede.

Serviços de planejamento

Devido ao custo e à complexidade, os métodos de serviço de planejamento a seguir estão sujeitos a limites separados de outros tipos de solicitações.

• Limitado a 1 solicitação por segundo por CID:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  As solicitações que violam essas limitações são rejeitadas com o erro: RESOURCE_EXHAUSTED.

• 1 QPS é calculado como 60 solicitações a cada 60 segundos.

• Limitado a 2 solicitações por segundo por CID:

  • KeywordPlanIdeaService.GenerateAdGroupTheme

Considere esses limites ao criar um plano de palavras-chave.

Objeto do plano de palavras-chave	Número máximo
KeywordPlan por conta	10.000
KeywordPlanAdGroup por KeywordPlan	200
KeywordPlanAdGroupKeyword por KeywordPlan	10.000
KeywordPlanCampaignKeyword (palavras-chave negativas)	1.000
KeywordPlanCampaign por KeywordPlan	1

Serviço de upload de conversões

• Limite de 2.000 conversões de chamadas ou cliques por solicitação:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  As solicitações que violam esses limites são rejeitadas com o erro: TOO_MANY_CONVERSIONS_IN_REQUEST.

Serviço de upload de ajustes de conversão

• Limite de 2.000 ajustes de conversão por solicitação:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  As solicitações que violam esses limites são rejeitadas com o erro: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

Serviços de orçamento de faturamento e conta

• Mutações só podem ser feitas em contas configuradas para faturamento mensal.

  As solicitações que violam essa limitação são rejeitadas com o erro: MUTATE_NOT_ALLOWED.

• Só é permitida uma 1 operação para solicitações de mutação.

  As solicitações que violam essa limitação são rejeitadas com o erro: TOO_MANY_MUTATE_OPERATIONS.

• Aguarde pelo menos 12 horas entre as mudanças de ordem de orçamento na mesma conta. Fazer mudanças antes de 12 horas pode resultar em falhas irreparáveis que só podem ser resolvidas pelo representante da sua conta do Google Ads.

Convites para contas de clientes

Os novos usuários podem ser convidados para contas de cliente existentes com o CustomerUserAccessService. Como esse recurso envia e-mails de convite para outros usuários, ele pode ser usado indevidamente. Por isso, há limitações no comportamento dele:

• Os usuários não podem receber mais de um convite pendente para a mesma conta de cliente. Se uma solicitação subsequente for feita para enviar um convite a um usuário que já tem um convite pendente, este erro será retornado: ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• As contas de cliente não podem ter mais de 70 convites pendentes ao mesmo tempo. Se uma solicitação for enviada e causar o excesso desse valor, o seguinte erro será retornado: ACCESS_INVITATION_ERROR_PENDING_INVITATIONS_LIMIT_EXCEEDED.

Dados do usuário

Os dados do usuário são gerenciados com o UserDataService e o OfflineUserDataJobService. Em uma operação de criação ou remoção UserData, cada conjunto de user_identifiers precisa ser específico para um único usuário.

Para fazer isso, um erro OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS ou UserDataError.TOO_MANY_USER_IDENTIFIERS é retornado quando há mais de 20 user_identifiers em um conjunto UserData.

Outros tipos de limites

Um campo repetido, como uma lista de operações, que tenha muitos itens em uma solicitação, pode gerar o erro: REQUEST_SIZE_LIMIT_EXCEEDED. Essa mesma mensagem de erro também pode ser causada por outros problemas.

Se você encontrar essa limitação e estiver fazendo solicitações que usam um campo repetido, tente reduzir o número de itens no campo repetido implantando uma lista de operações em uma solicitação de mutação.

Ao fazer uma consulta GAQL, o número máximo de itens em uma cláusula IN é 20.000. Se você exceder esse limite, um erro FILTER_HAS_TOO_MANY_VALUES será retornado.