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'une entrée non valide ou d'une indisponibilité temporaire du service.

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

  • 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'enum 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 arrêté d'attendre. Vérifiez les délais avant expiration côté client.
2 500 UNKNOWN Une erreur inconnue s'est produite. Vous trouverez peut-être plus d'informations dans le message d'erreur ou les détails. Traitez-le comme une erreur du serveur. Peut souvent être relancé après avoir laissé passer un intervalle 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 incorrect ou une valeur non valide. Erreur 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 raison de l'erreur. Utilisez ces détails pour corriger la requête. Ne relancez pas la requête avant de l'avoir corrigée.
4 504 DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Erreur du 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 tenté 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 du compte Google Ads. Ne relancez pas la requête avant d'avoir résolu les problèmes d'autorisation.
8 429 RESOURCE_EXHAUSTED Une ressource a été épuisée (par exemple, vous avez dépassé votre quota) ou un système est surchargé. Erreur client/serveur : nécessite généralement d'attendre. Implémentez un intervalle exponentiel entre les tentatives et réduisez potentiellement le taux de requêtes. Consultez Limites et quotas de l'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. Examinez les détails de l'erreur pour comprendre l'échec de la condition préalable. Ne relancez pas la requête avant d'avoir corrigé l'état.
10 409 ABORTED L'opération a été annulé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 après 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 compatible avec 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 message générique pour les problèmes côté serveur. Erreur du serveur : peut généralement être relancée avec un intervalle exponentiel entre les tentatives. Si le problème persiste, signalez-le.
14 503 UNAVAILABLE Le service est momentanément indisponible. Il s'agit probablement d'une condition temporaire. Erreur du 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 du 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 Guide de conception d'API : codes d'erreur.

Comprendre les détails de l'erreur

En plus du code de premier niveau, l'API Google Ads fournit des informations d'erreur plus spécifiques 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 : Identifiant 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'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.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

Dans cet exemple, malgré le INVALID_ARGUMENT de premier niveau, les détails GoogleAdsFailure vous indiquent que les champs name et description ont causé le 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 des erreurs dépend de la méthode que vous utilisez : appels d'API standards, échec partiel ou streaming.

Appels d'API standards et de streaming

Lorsqu'un appel d'API échoue sans utiliser d'échec partiel, y compris les appels en 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 cela comme une exception avec un attribut GoogleAdsFailure.

Échec partiel

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

Jobs par lots

Pour le traitement par lot, les erreurs liées à des opérations individuelles peuvent être identifiées en appelant BatchJobService.ListBatchJobResults une fois le job terminé. Chaque résultat d'opération inclura un champ status contenant des détails sur l'erreur si l'opération a échoué.

Identifiant de la demande

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

Vous pouvez trouver 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 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 ayant échoué, request-id est également disponible dans les en-têtes de réponse gRPC et les réponses HTTP, à l'exception des requêtes de streaming réussies.
  • 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 l'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. Inspecter les détails de l'erreur : analysez toujours le champ details de l'objet Status, en recherchant spécifiquement GoogleAdsFailure. Les éléments précis error_code, message et location dans GoogleAdsError fournissent les informations les plus exploitables pour le débogage et les commentaires des utilisateurs.

  2. Différencier les erreurs client des erreurs serveur :

    • Erreurs client : codes tels que INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, 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, UNKNOWN. Ces codes indiquent un problème temporaire avec le service d'API.

  3. Mettre en œuvre une stratégie de nouvelle tentative :

    • 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, 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 exponentiel entre les tentatives pour éviter le problème de "troupeau tonitruant" où de nombreux clients effectuent une nouvelle tentative simultanément.

  4. Consignez les erreurs de manière exhaustive : 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. Fournir des commentaires aux utilisateurs : en fonction des codes et des messages GoogleAdsError spécifiques, fournissez des commentaires clairs et utiles aux utilisateurs de votre application. Par exemple, au lieu de simplement indiquer "Une erreur s'est produite", vous pouvez indiquer "Le nom de la campagne est obligatoire" ou "L'ID du 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 permet de créer des applications plus stables et plus conviviales.

Précédent
Types d'erreurs
Suivant
Erreurs courantes