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 les problèmes de manière fluide, 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 :

  • Code d'erreur numérique.
  • Message d'erreur.
  • 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 générale 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 :

Code gRPC Code HTTP Nom de l'énumération Description Conseils
0 200 OK Aucune erreur ; indique que l'opération a réussi. N/A
1 499 CANCELLED L'opération a été annulée, généralement par le client. Cela signifie généralement que le client a cessé d'attendre. Vérifiez les délais avant expiration côté client.
2 500 UNKNOWN Une erreur inconnue s'est produite. Pour en savoir plus, consultez le message ou les détails de l'erreur. Traitez-le comme une erreur de serveur. Peut souvent être réessayé avec un délai entre les tentatives.
3 400 INVALID_ARGUMENT Le client a spécifié un argument non valide. Cela indique un problème qui empêche l'API de traiter la requête, comme un nom de ressource mal formé ou une valeur non valide. Erreur du client : vérifiez les paramètres de votre requête et assurez-vous qu'ils répondent aux exigences de l'API. Les détails de l'erreur fournissent généralement des informations sur l'argument non valide et sur la manière dont il l'est. Utilisez ces informations pour corriger la requête. Ne relancez pas la requête avant d'avoir résolu le problème.
4 504 DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Erreur de serveur : souvent temporaire. Envisagez de réessayer avec un intervalle exponentiel entre les tentatives.
5 404 NOT_FOUND Une entité demandée (par exemple, une campagne ou un groupe d'annonces) est introuvable. Erreur client : vérifiez l'existence et l'ID des ressources auxquelles vous essayez d'accéder. Ne relancez pas la requête avant d'avoir résolu le problème.
6 409 ALREADY_EXISTS L'entité que le client a essayé de créer existe déjà. Erreur client : évitez de créer des ressources en double. Vérifiez si la ressource existe avant d'essayer de la créer.
7 403 PERMISSION_DENIED L'appelant n'a pas l'autorisation d'exécuter l'opération spécifiée. Erreur client : vérifiez l'authentification, l'autorisation et les rôles utilisateur pour le compte Google Ads. Ne relancez pas la requête sans avoir résolu le problème d'autorisations.
8 429 RESOURCE_EXHAUSTED Soit une ressource est épuisée (par exemple, vous avez dépassé votre quota), soit un système est surchargé. Erreur client/serveur : vous devez généralement attendre. Mettez en œuvre un intervalle exponentiel entre les tentatives et réduisez potentiellement le taux de requêtes. Consultez Limites et quotas des API.
9 400 FAILED_PRECONDITION L'opération a été rejetée car le système n'est pas dans un état requis pour exécuter l'opération. Par exemple, un champ obligatoire est manquant. Erreur client : la requête est valide, mais l'état est incorrect. Consultez les détails de l'erreur pour comprendre l'échec de la précondition. Ne relancez pas la requête sans corriger l'état.
10 409 ABORTED L'opération a été abandonnée, généralement en raison d'un problème de simultanéité, tel qu'un conflit de transaction. Erreur du serveur : il est souvent possible de réessayer avec un court délai.
11 400 OUT_OF_RANGE L'opération a été tentée au-delà de la plage valide. Erreur client : corrigez la plage ou l'index.
12 501 UNIMPLEMENTED L'opération n'est pas implémentée ou n'est pas prise en charge par l'API. Erreur client : vérifiez la version de l'API et les fonctionnalités disponibles. Ne pas réessayer.
13 500 INTERNAL Une erreur interne s'est produite. Il s'agit d'un terme fourre-tout général pour les problèmes côté serveur. Erreur de serveur : généralement réessayable avec un intervalle exponentiel entre les tentatives. Si le problème persiste, signalez-le.
14 503 UNAVAILABLE Le service est actuellement indisponible. Il s'agit probablement d'une condition temporaire. Erreur de serveur : nous vous recommandons vivement de réessayer avec un intervalle exponentiel entre les tentatives.
15 500 DATA_LOSS Perte ou corruption de données irrécupérable. Erreur de serveur : rare. Indique un problème grave. Ne pas réessayer. Si le problème persiste, signalez-le.
16 401 UNAUTHENTICATED La requête ne dispose pas d'identifiants d'authentification valides. Erreur client : vérifiez vos jetons d'authentification et vos identifiants. Ne relancez pas la requête avant d'avoir résolu le problème d'authentification.

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

Comprendre les détails des erreurs

En plus 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 un proto GoogleAdsFailure, qui inclut une liste d'objets GoogleAdsError individuels.

Chaque objet GoogleAdsFailure 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 pour le débogage et l'assistance.

Chaque objet GoogleAdsError fournit les éléments suivants :

Exemple de détails d'une erreur

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

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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é le INVALID_ARGUMENT de premier niveau, les détails GoogleAdsFailure vous indiquent que les champs name et description sont à l'origine du problème et pourquoi (REQUIRED et TOO_SHORT, respectivement).

Localiser les détails des erreurs

La façon dont vous accédez aux détails des erreurs dépend de si vous utilisez des appels d'API standards, des échecs partiels ou le streaming.

Appels d'API standard et de flux

Lorsqu'un appel d'API échoue sans utiliser l'échec partiel, y compris les appels de streaming, l'objet GoogleAdsFailure est renvoyé dans les métadonnées de fin des 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 cette erreur sous la forme d'une exception avec un attribut GoogleAdsFailure.

Échec partiel

Si vous utilisez partialFailure, 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, GoogleAdsFailure est intégré dans un objet google.rpc.Status de la réponse.

Jobs par lots

Pour le traitement par lot, vous pouvez trouver les erreurs liées à des opérations individuelles en récupérant les résultats du job par lot une fois le job terminé. Chaque résultat d'opération inclut 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 résoudre les problèmes.

Vous trouverez le request-id à plusieurs endroits :

  • GoogleAdsFailure : si un appel d'API échoue et que GoogleAdsFailure est renvoyé, il contiendra 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 ayant abouti 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 ayant abouti.
  • SearchGoogleAdsStreamResponse : pour les requêtes de streaming, chaque message SearchGoogleAdsStreamResponse 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 des erreurs : analysez toujours le champ details de l'objet Status, en recherchant plus particulièrement GoogleAdsFailure. Les 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 côté client de celles côté serveur :

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

  3. Implémentez 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 nouvelles tentatives. Cela permet d'éviter de surcharger un service déjà sollicité. Par exemple, attendez 1 s, puis 2 s, puis 4 s, 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 de backoff pour éviter le problème de "tonnerre de troupeau" où de nombreux clients effectuent des nouvelles tentatives simultanément.

  4. Enregistrez les journaux de manière exhaustive : enregistrez l'intégralité de la réponse d'erreur, 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 les problèmes à l'assistance Google si nécessaire.

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

En suivant ces consignes, vous pourrez 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 conviviales.