Tipos de erro

Categorizamos os erros nas seguintes categorias gerais:

  • Autenticação
  • Erros que permitem uma nova tentativa
  • Validação
  • Relacionado à sincronização

Embora essas categorias não abranjam todos os erros possíveis, e algumas possam se encaixar em mais de uma categoria, elas podem servir como ponto de partida para estruturar o tratamento de erros do seu app. Consulte os recursos a seguir para mais detalhes sobre erros específicos:

  • Erros comuns fornece mais detalhes sobre um erro específico.
  • google.rpc.Status fornece detalhes sobre o modelo de erro lógico usado pela API.
  • Os códigos de erro canônicos fornecem uma lista e uma explicação dos códigos de erro canônicos definidos pelo gRPC e pelo HTTP no contexto da API Google Ads.

Erros de autenticação

A autenticação se refere à permissão concedida por um usuário ao seu app para acessar o Google Ads em nome dele. A autenticação é gerenciada por credenciais geradas pelo fluxo OAuth2.

O motivo mais comum para um erro de autenticação surgir de fatores além do seu controle é que o usuário autenticado revogou a permissão que deu ao seu app para agir em nome dele. Por exemplo, se o app gerencia contas separadas do Google Ads para clientes independentes e faz a autenticação separadamente como cada cliente ao gerenciar a conta dele, um cliente pode revogar o acesso do app a qualquer momento. Dependendo de quando o acesso foi revogado, a API pode retornar diretamente um erro AuthenticationError.OAUTH_TOKEN_REVOKED ou os objetos de credencial integrados nas bibliotecas de cliente podem gerar uma exceção de token revogado. Em qualquer caso, se o app tiver uma interface para os clientes, ele poderá pedir que eles reiniciem o fluxo do OAuth2 para restabelecer a permissão do app para agir em nome deles.

Da mesma forma, se o projeto na nuvem do Google Cloud tiver apenas o nível de acesso de teste e tentar fazer solicitações em uma conta de produção (não de teste), a API vai retornar um AuthorizationError cujo valor de tipo enumerado depende da versão da API:

Erros que permitem uma nova tentativa

Alguns erros, como TRANSIENT_ERROR ou INTERNAL_ERROR, podem indicar um problema temporário que pode ser resolvido repetindo a solicitação após uma pequena pausa.

Para solicitações iniciadas pelo usuário, uma estratégia é indicar imediatamente um erro na interface e dar ao usuário a opção de acionar uma nova tentativa. Como alternativa, seu app pode primeiro tentar novamente a solicitação automaticamente, expondo o erro na interface após atingir um número máximo de novas tentativas ou um tempo total de espera do usuário.

Para solicitações iniciadas no back-end, seu app precisa repetir automaticamente a solicitação até um número máximo de novas tentativas.

Ao repetir solicitações, use uma política de espera exponencial com jitter aleatório. Por exemplo, se você pausar 5 segundos antes da primeira nova tentativa, poderá pausar 10 segundos após a segunda e 20 segundos após a terceira, adicionando um pequeno atraso aleatório a cada intervalo para evitar picos de novas tentativas sincronizadas. A espera exponencial ajuda a garantir que você não esteja chamando a API de forma muito agressiva. Se um erro persistir depois de esgotar as novas tentativas, registre o request-id da resposta para solução de problemas.

Erros de validação

Erros de validação indicam que a entrada de uma operação não foi aceitável. Exemplos incluem PolicyViolationError, DateError, DateRangeError, StringLengthError e UrlFieldError.

Os erros de validação ocorrem com mais frequência em solicitações iniciadas pelo usuário, em que ele inseriu uma entrada inválida. Nesses casos, forneça uma mensagem de erro adequada ao usuário com base no erro específico da API recebido. Você também pode validar a entrada do usuário para erros comuns antes de fazer uma chamada de API, tornando seu app mais responsivo e o uso da API mais eficiente. Para solicitações do back-end, seu app pode adicionar a operação com falha a uma fila para que um operador humano analise.

Muitos apps do Google Ads possuem um banco de dados local para armazenar os objetos do Google Ads deles. Um desafio dessa abordagem é que o banco de dados local pode ficar dessincronizado com os objetos reais no Google Ads. Por exemplo, um usuário pode excluir um grupo de anúncios diretamente no Google Ads, mas o app e o banco de dados local não sabem da mudança e continuam emitindo chamadas de API como se o grupo de anúncios existisse. Esses problemas de sincronização podem se manifestar como vários erros, como DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, e muitos outros.

Para solicitações iniciadas pelo usuário, uma estratégia é alertar o usuário sobre um possível problema de sincronização, iniciar imediatamente um job que recupera a classe relevante de objetos do Google Ads e atualiza o banco de dados local. Em seguida, peça ao usuário para atualizar a interface.

Para solicitações de back-end, alguns erros fornecem informações suficientes para que o app corrija automaticamente e de forma incremental o banco de dados local. Por exemplo, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD deve fazer com que seu app marque o anúncio como removido no banco de dados local. Erros que não podem ser tratados dessa forma podem fazer com que o app inicie uma tarefa de sincronização mais completa ou seja adicionado a uma fila para revisão por um operador humano.

Avançar
Compreenda os erros da API