Comprendre les erreurs d'API

Ce guide explique comment l'API Google Ads gère les erreurs et communique à leur sujet. 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. Vous trouverez peut-être plus d'informations dans le message ou les détails de l'erreur. Traitez-la 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 respectent les exigences de l'API. Les détails de l'erreur fournissent généralement des informations sur l'argument non valide et sur la façon 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 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 pour le compte Google Ads. Ne relancez pas la requête sans avoir résolu les problèmes 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 : nécessite généralement d'attendre. Mettez en œuvre un intervalle exponentiel entre les tentatives et réduisez potentiellement le taux de requêtes. Consultez la page 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, il manque un champ obligatoire. 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é annulée, généralement en raison d'un problème de simultanéité, tel qu'un conflit de transaction. Erreur de 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 ni 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'une catégorie générale pour les problèmes côté serveur. Erreur du serveur : peut généralement être corrigée en réessayant 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 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 demande, 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 comporter des détails GoogleAdsFailure comme celui-ci :

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.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 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 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 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, GoogleAdsFailure est intégré dans un objet google.rpc.Status de la réponse.

Jobs par lots

Pour le traitement par lot, les erreurs liées à des opérations individuelles peuvent être trouvées en appelant BatchJobService.ListBatchJobResults une fois le job terminé. Chaque résultat d'opération inclut un champ status contenant des informations 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 résoudre les problèmes.

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 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 les réponses HTTP, à l'exception des requêtes de flux 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 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'objet Status, en recherchant plus particulièrement GoogleAdsFailure. Les error_code, message et location précis dans GoogleAdsError fournissent les informations les plus utiles pour le débogage et les commentaires des utilisateurs.

  2. Faites la différence entre les erreurs côté client et côté serveur :

    • Erreurs client : codes tels que INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Ces erreurs nécessitent de modifier la requête ou l'état/les 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 et UNKNOWN. Ces codes suggèrent un problème temporaire avec le service d'API.

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

    • Quand réessayer : réessayez uniquement en cas d'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 submerger un service déjà surchargé. Par exemple, attendez 1 s, puis 2 s, puis 4 s, et ainsi de suite jusqu'à atteindre le nombre maximal de tentatives ou le 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 "troupeau tonnant", 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 les problèmes à l'assistance Google si nécessaire.

  5. Fournissez des commentaires aux utilisateurs : en fonction des codes et 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 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.

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