Tipos de erro

Classificamos os erros nas seguintes categorias amplas:

• Autenticação
• Nova tentativa
• Validação
• Relacionado à sincronização

Embora essas categorias não englobem todos os erros possíveis e algumas podem se encaixar em mais de uma categoria, elas podem servir como um ponto de partida para estruturar o tratamento de erros do seu app. Consulte a documentação Erros comuns para conferir mais detalhes sobre um erro específico.

Erros de autenticação

A autenticação indica se o app recebeu permissão de um usuário para acessar o Google Ads em nome dele. A autenticação é gerenciada por meio de credenciais geradas pelo fluxo do OAuth2.

O motivo mais comum para o surgimento de um erro de autenticação devido a fatores que estão fora do seu controle é que o usuário autenticado revogou a permissão deu ao app para agir em nome dele. Por exemplo, se o seu aplicativo gerencia contas separadas do Google Ads para clientes independentes e se autentica separadamente para cada um ao gerenciar a conta deles, um cliente pode revogar o acesso ao seu aplicativo a qualquer momento. Dependendo de quando seu 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 revogação de token. Nos dois casos, se o app tiver uma interface para seus clientes, ele poderá solicitar que eles reiniciem o fluxo do OAuth2 para restabelecer a permissão do app para agir em nome deles.

Erros que permitem uma nova tentativa

Alguns erros, como TRANSIENT_ERROR ou INTERNAL_ERROR, podem indicar um problema temporário que pode ser resolvido ao repetir a solicitação após uma breve 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, o app pode tentar novamente a solicitação automaticamente, expondo o erro na interface apenas depois de atingir um número máximo de novas tentativas ou o tempo total de espera do usuário.

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

Ao repetir solicitações, use uma política de espera exponencial. Por exemplo, se você pausar 5 segundos antes da primeira tentativa, poderá pausar 10 segundos após a segunda e 20 segundos após a terceira, O backoff exponencial ajuda a garantir que você não chame a API de maneira muito rigorosa.

Erros de validação

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

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

Erros relacionados à sincronização

Muitos apps do Google Ads têm um banco de dados local para armazenar os objetos do Google Ads. Um desafio dessa abordagem é que o banco de dados local pode ficar fora de sincronia 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 aplicativo e o banco de dados local não sabem da mudança e continuam a emitir chamadas de API como se o grupo de anúncios existisse. Esses problemas de sincronização podem se manifestar como uma variedade de erros, como DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD e muitos outros.

No caso de 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 recupere a classe relevante de objetos do Google Ads e atualize o banco de dados local e, em seguida, solicite que o usuário atualize a interface.

Para solicitações de back-end, alguns erros fornecem informações suficientes para que o app corrija o banco de dados local de forma automática e incremental. Por exemplo, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD precisa fazer com que o app marque esse anúncio como removido no banco de dados local. Os erros que não podem ser tratados dessa maneira podem fazer com que seu app inicie um job de sincronização mais completo ou seja adicionado a uma fila para revisão de um operador humano.