Types d'erreurs

Nous avons classé les erreurs dans les grandes catégories suivantes :

• Authentification
• Erreurs pouvant être réessayées
• Validation
• Lié à 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. Consultez les ressources suivantes pour en savoir plus sur des erreurs spécifiques :

• La section Erreurs courantes fournit plus de détails sur une erreur particulière.
• google.rpc.Status fournit des détails sur le modèle d'erreur logique utilisé par l'API.
• Codes d'erreur canoniques : liste et explication des codes d'erreur canoniques définis par gRPC et HTTP dans le contexte de l'API Google Ads.

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 via des identifiants générés par le flux OAuth2.

La raison la plus courante pour laquelle une erreur d'authentification survient en raison de facteurs indépendants de votre volonté est que l'utilisateur authentifié a révoqué l'autorisation qu'il avait 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 de son compte, un client peut révoquer l'accès de votre application à tout moment. Selon le moment où votre accès a été révoqué, l'API peut renvoyer directement une erreur AuthenticationError.OAUTH_TOKEN_REVOKED, ou les objets d'identifiants 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 de votre application à agir en leur nom.

De même, si votre projet Google Cloud ne dispose que du niveau d'accès test et tente d'effectuer des requêtes sur un compte de production (autre que de test), l'API renvoie une erreur AuthorizationError dont la valeur d'énumération dépend de la version de l'API :

• À partir de v25 : renvoie AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION.
• v24 et versions antérieures : renvoie AuthorizationError.ACTION_NOT_PERMITTED.

Erreurs pouvant être réessayées

Certaines erreurs, telles que TRANSIENT_ERROR ou INTERNAL_ERROR, peuvent indiquer un problème temporaire qui peut être résolu en relançant la requête après une courte pause.

Pour les requêtes initiées par l'utilisateur, une stratégie consiste à indiquer immédiatement une erreur dans votre UI et à donner à l'utilisateur la possibilité de déclencher une nouvelle tentative. Votre application peut également réessayer automatiquement la requête, en n'affichant l'erreur dans l'interface utilisateur qu'après avoir atteint un nombre maximal de tentatives ou un temps d'attente total de l'utilisateur.

Pour les requêtes initiées sur le backend, votre application doit automatiquement relancer la requête jusqu'à un nombre maximal de tentatives.

Lorsque vous relancez des requêtes, utilisez une règle d'intervalle exponentiel entre les tentatives avec une gigue aléatoire. Par exemple, si vous attendez d'abord cinq secondes avant la première nouvelle tentative, vous pouvez attendre 10 secondes après la deuxième et 20 secondes après la troisième, en ajoutant un petit délai aléatoire à chaque intervalle pour éviter les pics de nouvelles tentatives synchronisées. L'intervalle exponentiel entre les tentatives permet de s'assurer que vous n'appelez pas l'API de manière trop agressive. Si une erreur persiste après avoir épuisé les nouvelles tentatives, consignez le request-id de la réponse pour le dépannage.

Erreurs de validation

Les erreurs de validation indiquent qu'une entrée d'une opération n'était pas acceptable. Exemples : PolicyViolationError, DateError, DateRangeError, StringLengthError et UrlFieldError.

Les erreurs de validation se produisent le plus souvent dans les requêtes initiées par l'utilisateur, lorsqu'un utilisateur 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 l'examine.

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 problèmes 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 ne sont pas au courant de la modification 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 et bien d'autres.

Pour les requêtes initiées par l'utilisateur, une stratégie consiste à l'alerter d'un éventuel problème de synchronisation, à lancer immédiatement un job qui récupère la classe d'objets Google Ads concernée et met à jour la base de données locale, puis à inviter l'utilisateur à actualiser l'interface utilisateur.

Pour les requêtes de backend, certaines erreurs fournissent suffisamment d'informations pour que votre application corrige automatiquement et de manière incrémentielle votre base de données locale. Par exemple, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD doit amener votre application à marquer cette annonce comme supprimée dans 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'un job de synchronisation plus complet par votre application ou être ajoutées à une file d'attente pour qu'un opérateur humain les examine.