Limites e cotas de APIs

A Google Ads API 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 abaixo resume alguns dos limites e cotas importantes que você precisa conhecer.

Tipo de solicitação, limitação e código do erro
Solicitações paginadas 10.000 linhas por página INVALID_PAGE_SIZE
Operações com acesso básico 15.000 operações de API por dia RESOURCE_EXHAUSTED
Modificar solicitações 10.000 operações por solicitação TOO_MANY_MUTATE_OPERATIONS
Solicitações do serviço de planejamento 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 orçamento da conta e faturamento 1 operação por solicitação de mutação TOO_MANY_MUTATE_OPERATIONS

Limites diários de operações de 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 das solicitações GET e das operações mutate. Os limites para operações diárias da API dependem do nível de acesso do token de desenvolvedor. O guia sobre 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 da 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, o tamanho da página ou use streaming. Para mutates, envie menos operações por solicitação.

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

Modificar solicitações

Além de ser deduzida da 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 abaixo 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 conta como uma operação de API, independentemente do número de lotes.

Solicitações paginadas

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

As solicitações paginadas, como as de pesquisa, também estão sujeitas à limitação de Page size cannot exceed 10,000 rows e serão rejeitadas se violarem esse limite, com o erro: INVALID_PAGE_SIZE.

Para mais detalhes sobre paginação, consulte Como percorrer resultados.

Outros tipos de solicitações

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

Alguns exemplos dessas solicitações incluem:

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 um GoogleAdsFailure, como de 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 de conectividade de rede.

Serviços de planejamento

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

Lembre-se desses limites ao criar um plano de palavras-chave.

Objeto do plano de palavra-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

Serviço de upload de ajustes de conversão

Serviços de faturamento e orçamento da conta

  • As alteraçõ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.

  • Apenas a operação 1 é permitida 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 para fazer alterações nos pedidos com limite de orçamento na mesma conta. Fazer as alterações antes desse período pode resultar em falhas irrecuperáveis que só podem ser resolvidas pelo representante da sua conta do Google Ads.

Convites para contas de clientes

Novos usuários podem ser convidados para contas de cliente com CustomerUserAccessService. Como essa funcionalidade envia e-mails de convite para outros usuários, ela tem o potencial de ser utilizada indevidamente e, portanto, há limitações ao comportamento:

Dados do usuário

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

Para aplicar 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 tem 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 mutate.

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.