Nous avons classé les erreurs dans les grandes catégories suivantes:
- Authentification
- Nouvelle tentative
- Validation
- Concernant la synchronisation
Bien que ces catégories n'englobent pas toutes les erreurs possibles et que certaines puissent appartenir à plusieurs catégories, elles peuvent néanmoins servir de point de départ pour structurer la gestion des erreurs de votre application. Pour plus de détails sur une erreur particulière, consultez la section Erreurs courantes.
Erreurs d'authentification
L'authentification indique si un utilisateur a autorisé votre application à accéder à Google Ads en son nom. L'authentification est gérée à l'aide des identifiants générés par le flux OAuth2.
Le plus souvent, une erreur d'authentification provient de facteurs que vous ne contrôlez pas. C'est parce que l'utilisateur authentifié a révoqué l'autorisation qu'il a accordée à votre application pour agir en son nom. Par exemple, si votre application gère des comptes Google Ads distincts pour des clients indépendants et s'authentifie séparément pour chaque client lors de la gestion du compte de ce client, un client peut révoquer l'accès à votre application à tout moment. Selon la date à laquelle votre accès a été révoqué, l'API peut renvoyer directement une erreur AuthenticationError.OAUTH_TOKEN_REVOKED, ou les objets d'identification intégrés dans les bibliothèques clientes peuvent générer une exception de jeton révoqué. Dans les deux cas, si votre application dispose d'une interface utilisateur pour vos clients, elle peut leur demander de relancer le flux OAuth2 pour rétablir l'autorisation d'agir en leur nom.
Erreurs récupérables
Certaines erreurs, telles que TRANSIENT_ERROR ou INTERNAL_ERROR, peuvent indiquer un problème temporaire qui peut être résolu en effectuant une nouvelle tentative de la requête après une courte pause.
Pour les requêtes déclenchées par l'utilisateur, une stratégie consiste à indiquer immédiatement une erreur dans votre interface utilisateur et à lui donner la possibilité de déclencher une nouvelle tentative. Votre application peut d'abord relancer automatiquement la requête, n'exposant l'erreur dans l'interface utilisateur qu'une fois le nombre maximal de tentatives atteint ou le temps d'attente total utilisateur atteint.
Pour les requêtes lancées sur le backend, votre application doit automatiquement relancer la requête, dans la limite du nombre maximal de tentatives.
Lorsque vous relancez des requêtes, utilisez une règle d'intervalle exponentiel entre les tentatives. Par exemple, si vous mettez d'abord en pause cinq secondes avant la première tentative, vous pouvez suspendre 10 secondes après la deuxième et 20 secondes après la troisième. L'intervalle exponentiel entre les tentatives permet de s'assurer que vous n'appelez pas l'API de manière trop agressive.
Erreurs de validation
Les erreurs de validation indiquent qu'une entrée associée à une opération n'était pas acceptable.
Par exemple, PolicyViolationError, DateError, DateRangeError, StringLengthError et UrlFieldError.
Les erreurs de validation se produisent le plus souvent dans les requêtes déclenchées par l'utilisateur, pour lesquelles celui-ci a saisi une entrée non valide. Dans ce cas, vous devez fournir un message d'erreur approprié à l'utilisateur en fonction de l'erreur d'API spécifique que vous avez reçue. Vous pouvez également valider les entrées utilisateur pour détecter les erreurs courantes avant d'effectuer un appel d'API, ce qui rend votre application plus réactive et votre utilisation de l'API plus efficace. Pour les requêtes provenant du backend, votre application peut ajouter l'opération ayant échoué à une file d'attente pour qu'un opérateur humain puisse l'examiner.
Erreurs liées à la synchronisation
De nombreuses applications Google Ads gèrent une base de données locale pour stocker leurs objets Google Ads. L'un des inconvénients de cette approche est que la base de données locale peut ne plus être synchronisée avec les objets réels dans Google Ads. Par exemple, un utilisateur peut supprimer un groupe d'annonces directement dans Google Ads, mais l'application et la base de données locale n'en sont pas au courant et continuent d'émettre des appels d'API comme si le groupe d'annonces existait. Ces problèmes de synchronisation peuvent se manifester par diverses erreurs, telles que DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, entre autres.
Pour les requêtes déclenchées par l'utilisateur, une stratégie consiste à alerter l'utilisateur d'un possible problème de synchronisation, à lancer immédiatement une tâche qui récupère la classe d'objets Google Ads pertinente et à mettre à jour la base de données locale, puis à inviter l'utilisateur à actualiser l'interface utilisateur.
Pour les requêtes backend, certaines erreurs fournissent suffisamment d'informations pour que votre application corrige automatiquement et progressivement votre base de données locale. Par exemple, avec CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, votre application doit marquer cette annonce comme supprimée de votre base de données locale. Les erreurs que vous ne pouvez pas gérer de cette manière peuvent entraîner le lancement d'une tâche de synchronisation plus complète ou l'ajout à une file d'attente pour examen par un opérateur humain.