Gérer les erreurs d'API

Lorsque vous envoyez une requête à l'API Google Ads, elle peut échouer pour différentes raisons. Par exemple, vous avez peut-être fourni un argument non valide ou votre compte a peut-être atteint la limite de création de campagnes. Dans ce cas, l'API renvoie une erreur pour vous indiquer ce qui s'est mal passé.

Ce guide explique comment lire et gérer les erreurs d'API afin de créer des applications plus robustes.

Structure des erreurs

Si vous utilisez l'une de nos bibliothèques clientes, les erreurs d'API sont signalées comme des exceptions. Ces exceptions contiennent des détails qui vous aident à comprendre pourquoi l'erreur s'est produite.

L'API Google Ads renvoie les informations d'erreur dans un format standard. En cas d'erreur, la réponse contiendra un objet GoogleAdsFailure. Cet objet contient une liste d'objets GoogleAdsError individuels, chacun détaillant une erreur spécifique.

Chaque objet GoogleAdsError fournit les éléments suivants :

• error_code : code d'erreur spécifique qui vous indique le type d'erreur, par exemple AuthenticationError.NOT_ADS_USER.
• message : description lisible par l'humain de la raison pour laquelle l'erreur s'est produite.
• trigger : valeur à l'origine de l'erreur, par exemple "1234".
• location : détails sur la partie de la requête à l'origine de l'erreur, par exemple un nom de champ spécifique.

En plus de la liste des erreurs, GoogleAdsFailure contient un requestId, qui est un identifiant unique pour la requête API ayant entraîné une erreur.

Exemple d'erreur

Voici un exemple d'erreur au format JSON. Cette erreur indique que le champ name de l'élément ad_group à l'index 0 est manquant dans la requête.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Pour en savoir plus sur les erreurs d'API, consultez Comprendre les erreurs d'API.

Exemples de bibliothèques clientes

La section suivante explique comment gérer les erreurs dans différentes bibliothèques clientes.

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an
  // API request. Instances of this exception have a message and a
  // GoogleAdsFailure that contains a collection of GoogleAdsErrors that
  // indicate the underlying causes of the GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying"
          + " errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError :
      gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

try {
    // Make an API call.
    ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(
            f"\tError with message '{error.message}' and code "
            f"'{error.error_code}'."
        )

begin
  # Make an API call.
  ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
  puts "API call failed with request ID: #{e.request_id}"
  e.failure.errors.each do |error|
    puts "\t#{error.error_code}: #{error.message}"
  end
end

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n",
      [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

Enregistrer les journaux

Pour résoudre les erreurs, capturez les journaux d'erreurs renvoyés par le serveur de l'API Google Ads et examinez leur contenu. Suivez les instructions ci-dessous pour activer la journalisation et capturer les journaux d'API.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Gérer les erreurs

Si vous rencontrez une erreur, procédez comme suit :

1. Interceptez l'exception et capturez les journaux : commencez par intercepter les exceptions et, si vous le souhaitez, capturez les journaux de l'API.
2. Examinez la liste errors : examinez chaque GoogleAdsError dans l'objet GoogleAdsFailure. error_code et message vous indiqueront ce qui n'a pas fonctionné.
3. Vérifiez la valeur location : le champ location peut vous aider à identifier l'endroit où le problème s'est produit dans votre requête.
4. Consultez la documentation : pour des codes d'erreur spécifiques, consultez la page des erreurs courantes ou la documentation de référence complète sur les codes d'erreur pour en savoir plus sur l'erreur et comment la corriger.
5. Ajustez votre requête : corrigez votre requête API en fonction du message d'erreur. Par exemple, si vous voyez REQUIRED_FIELD_MISSING, assurez-vous de fournir ce champ dans votre requête.
6. Consignez le request_id : si vous ne parvenez pas à résoudre une erreur et que vous devez contacter l'assistance, incluez les journaux complets des requêtes et des réponses pour la requête ayant échoué. Veillez à inclure request_id. Cet ID aide les ingénieurs Google à localiser les détails de la requête ayant échoué dans les journaux du serveur de l'API Google Ads et à examiner votre problème.

Étapes suivantes

• Consultez la section Erreurs courantes pour obtenir la liste des problèmes fréquents et leurs solutions.
• Pour en savoir plus sur les techniques avancées de gestion des erreurs, y compris la logique de nouvelle tentative et l'échec partiel, consultez Comprendre les erreurs d'API.