Comprendre les erreurs d'API

Ce guide explique comment l'API Google Ads gère et communique les erreurs. Il est essentiel de comprendre la structure et la signification des erreurs d'API pour créer des applications robustes capables de gérer correctement les problèmes, qu'il s'agisse d'entrées non valides ou d'une indisponibilité temporaire du service.

L'API Google Ads suit le modèle d'erreur standard des API Google, qui est basé sur les codes d'état gRPC. Chaque réponse d'API qui génère une erreur inclut un objet Status contenant les éléments suivants :

• Un code d'erreur numérique.
• Un message d'erreur.
• Des informations supplémentaires facultatives sur l'erreur.

Codes d'erreur canoniques

L'API Google Ads utilise un ensemble de codes d'erreur canoniques définis par gRPC et HTTP. Ces codes fournissent une indication de haut niveau du type d'erreur. Vous devez toujours vérifier ce code numérique en premier pour comprendre la nature fondamentale du problème.

Le tableau suivant récapitule les codes les plus courants que vous pouvez rencontrer lorsque vous utilisez l'API Google Ads :

Pour en savoir plus sur ces codes, consultez le Guide de conception d'API - Codes d'erreur.

Comprendre les détails de l'erreur

Au-delà du code de premier niveau, l'API Google Ads fournit des informations plus spécifiques sur les erreurs dans le champ details de l'objet Status. Ce champ contient souvent contient un GoogleAdsFailure proto, qui inclut une liste d'objets individuels GoogleAdsError.

Chaque GoogleAdsFailure objet contient les éléments suivants :

• errors : liste d'objets GoogleAdsError, chacun détaillant une erreur spécifique qui s'est produite.
• request_id: ID unique de la requête, utile à des fins de débogage et d'assistance.

Chaque GoogleAdsError objet fournit les éléments suivants :

• errorCode : code d'erreur plus précis et spécifique à l'API Google Ads , tel que AuthenticationError.NOT_ADS_USER.
• message: description lisible par l'utilisateur de l'erreur spécifique.
• trigger: valeur à l'origine de l'erreur, le cas échéant.
• location: décrit l'emplacement de l'erreur dans la requête, y compris les chemins d'accès aux champs.
• details: informations supplémentaires sur l'erreur, telles que les raisons d'erreur non publiées.

Exemple de détails d'erreur

Lorsque vous recevez une erreur, votre bibliothèque cliente vous permet d'accéder à ces informations. Par exemple, une erreur INVALID_ARGUMENT (code 3) peut comporter des détails GoogleAdsFailure comme suit :

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

Dans cet exemple, malgré l'erreur INVALID_ARGUMENT de premier niveau, les GoogleAdsFailure détails vous indiquent que les name et description champs sont à l'origine du problème et pourquoi (REQUIRED et TOO_SHORT, respectivement).

Localiser les détails de l'erreur

La façon dont vous accédez aux détails de l'erreur dépend de si vous utilisez des appels d'API standards, un échec partiel ou un streaming.

Appels d'API standards et de streaming

Lorsqu'un appel d'API échoue sans utiliser d'échec partiel, y compris les appels de streaming, l'objet GoogleAdsFailure est renvoyé dans le cadre des métadonnées de fin dans les en-têtes de réponse gRPC. Si vous utilisez REST pour les appels standards, GoogleAdsFailure est renvoyé dans la réponse HTTP. Les bibliothèques clientes affichent généralement cela comme une exception avec un GoogleAdsFailure attribut.

Échec partiel

Si vous utilisez un échec partiel, les erreurs liées aux opérations ayant échoué sont renvoyées dans le champ partial_failure_error de la réponse, et non dans les en-têtes de réponse. Dans ce cas, le GoogleAdsFailure est intégré dans un objet google.rpc.Status de la réponse.

Jobs par lots

Pour le traitement par lots, vous pouvez trouver les erreurs liées aux opérations individuelles en récupérant les résultats du job par lots une fois le job terminé. Chaque résultat d'opération inclura un champ status contenant les détails de l'erreur si l'opération a échoué.

Identifiant de la demande

request-id est une chaîne unique qui identifie votre requête API et qui est essentielle pour le dépannage.

Vous pouvez trouver request-id à plusieurs endroits :

• GoogleAdsFailure : si un appel d'API échoue et que GoogleAdsFailure est renvoyé, il contient un request_id.
• Métadonnées de fin : pour les requêtes réussies et celles ayant échoué, request-id est disponible dans les métadonnées de fin de la réponse gRPC.
• En-têtes de réponse : pour les requêtes réussies et celles ayant échoué, request-id est également disponible dans les en-têtes de réponse gRPC et HTTP, à l’exception des requêtes de streaming réussies.
• SearchGoogleAdsStreamResponse : pour les requêtes de streaming, chaque SearchGoogleAdsStreamResponse message contient un champ request_id.

Lorsque vous consignez des erreurs ou contactez l'assistance, veillez à inclure le request-id pour faciliter le diagnostic des problèmes.

Bonnes pratiques pour la gestion des erreurs

Pour créer des applications résilientes, mettez en œuvre les bonnes pratiques suivantes :

1. Inspectez les détails de l'erreur : analysez toujours le champ details de l'Status objet, en particulier en recherchant GoogleAdsFailure. Les champs errorCode, message, et location précis dans GoogleAdsError fournissent les informations les plus exploitables pour le débogage et les commentaires des utilisateurs.

2. Distinguez les erreurs client des erreurs de serveur :

   • Erreurs client : codes tels que INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Ces erreurs nécessitent des modifications de la requête ou de l'état/des identifiants de votre application. Ne relancez pas la requête sans avoir résolu le problème.
   • Erreurs de serveur : codes tels que UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Ces erreurs suggèrent un problème temporaire avec le service d'API.

3. Mettez en œuvre une stratégie de nouvelles tentatives :

   • Quand réessayer : ne réessayez que pour les erreurs de serveur temporaires telles que UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN et ABORTED.
   • Intervalle exponentiel entre les tentatives : utilisez un algorithme d'intervalle exponentiel entre les tentatives pour attendre des périodes de plus en plus longues entre les tentatives. Cela permet d'éviter de surcharger un service déjà sollicité. Par exemple, attendez 1 seconde, puis 2 secondes, puis 4 secondes, et ainsi de suite jusqu'à atteindre un nombre maximal de tentatives ou un temps d'attente total.
   • Gigue : ajoutez une petite quantité aléatoire de "gigue" aux délais d'intervalle entre les tentatives pour éviter le problème de "tonnage" où de nombreux clients réessayent simultanément.

4. Consignez les informations de manière approfondie : consignez la réponse d'erreur complète, y compris tous les détails, en particulier l'ID de la requête. Ces informations sont essentielles pour le débogage et pour signaler des problèmes à l'assistance Google si nécessaire.

5. Fournissez des commentaires aux utilisateurs : en fonction des codes et des messages spécifiques GoogleAdsError, fournissez des commentaires clairs et utiles aux utilisateurs de votre application. Par exemple, au lieu de simplement "Une erreur s'est produite", vous pouvez indiquer "Le nom de la campagne est obligatoire" ou "L'ID de groupe d'annonces fourni est introuvable".

En suivant ces consignes, vous pouvez diagnostiquer et gérer efficacement les erreurs renvoyées par l'API Google Ads, ce qui vous permettra de créer des applications plus stables et plus conviviales.