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

Tipo de solicitação, limitação e código de 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
Receber solicitações 1.000 solicitações 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 do serviço de orçamento da conta e de faturamento 1 operação por solicitação de mutação TOO_MANY_MUTATE_OPERATIONS

Limites de operação diária da API

Os limites de uso diário 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 operações mut. Os limites das operações diárias da API dependem do nível de acesso do token de desenvolvedor. O guia Níveis de acesso e uso permitido descreve os limites de operação de API específicos 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 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 que excede 64 MB. Para evitar esse limite, reduza o número de campos selecionados, o tamanho da página ou use 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 mensagens de código e erros de gRPC.

Receber solicitações (uso suspenso)

Solicitações de recebimento, por exemplo, com o método GetCampaign na CampaignService, têm limitações de uso diárias separadas dos limites de operações, que são descritos no guia de níveis de acesso e uso permitido.

Ao contrário das operações diárias, os limites das solicitações "get" não variam de acordo com o nível de acesso. Todos os tokens de desenvolvedor, incluindo aqueles com acesso padrão, são limitados a 1.000 solicitações de recebimento por dia.

Ao contrário das solicitações de pesquisa, as solicitações "get" são caras, porque todos os dados de atributos são recuperados. Por isso, recomendamos o uso da pesquisa em vez da busca quando possível.

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

Modificar solicitações

Além de ser contabilizada na cota diária de operações do usuário, uma solicitação de modificaçã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.

Limites e considerações adicionais para serviços e tipos de solicitação específicos estão descritos abaixo.

Solicitações de pesquisa

Uma solicitação Search ou SearchStream conta 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 do usuário. No entanto, as solicitações de paginação que contêm um token de página expirado ou inválido gerarão uma exceção e serão contabilizadas na cota de operação diária.

As solicitações paginadas, como de pesquisas, também estão sujeitas à limitação 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 os resultados.

Outros tipos de solicitações

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

Veja alguns exemplos dessas solicitações:

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

As solicitações rejeitadas com um GoogleAdsFailure ainda são consideradas 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ções diárias do usuário, já que as solicitações nunca alcançariam o 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ão

Serviço de upload de ajustes de conversão

Serviços de faturamento e orçamento da conta

  • As 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.

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

    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 alterações do pedido com limite de orçamento na mesma conta. As alterações feitas antes desse período podem resultar em falhas irrecuperá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 essa funcionalidade envia e-mails de convite para outros usuários, ela pode ser usada indevidamente. Por isso, o comportamento dela tem limitações:

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/remoção de UserData, cada conjunto de user_identifiers precisa ser específico de 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. Esta mesma mensagem de erro também pode ser devido a 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.