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 pouvez fournir un argument non valide ou votre compte peut avoir atteint sa limite de création de campagnes. Dans ce cas, l'API renvoie une erreur pour vous indiquer ce qui n'a pas fonctionné.

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 sous forme d'exceptions. Ces exceptions contiennent des informations qui vous aident à comprendre pourquoi l'erreur s'est produite.

L'API Google Ads renvoie les informations sur les erreurs dans un format standard. En cas d'erreur, la réponse contient 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 indique le type d'erreur, par exemple AuthenticationError.NOT_ADS_USER.
• message : description lisible 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 qui a provoqué l'erreur, comme le nom d'un 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 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.v22.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 notre guide.

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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() 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 '{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, voici la marche à suivre :

1. Interceptez l'exception et capturez les journaux : commencez par intercepter les exceptions et, si vous le souhaitez, capturez les journaux d'API.
2. Examinez la liste errors : examinez chaque GoogleAdsError dans l'objet GoogleAdsFailure. Les codes error_code et message vous indiqueront ce qui n'a pas fonctionné.
3. Vérifiez la valeur de location : le champ location peut vous aider à identifier l'emplacement du problème dans votre requête.
4. Consultez la documentation : pour les codes d'erreur spécifiques, consultez la page des erreurs courantes ou la référence complète des codes d'erreur pour en savoir plus sur l'erreur et sur la façon de la corriger.
5. Ajustez votre demande : corrigez votre demande d'API en fonction du message d'erreur. Par exemple, si vous voyez REQUIRED_FIELD_MISSING, assurez-vous de fournir ce champ dans votre demande.
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 de leurs solutions.
• Pour en savoir plus sur les techniques de gestion des erreurs avancées, y compris la logique de nouvelle tentative et l'échec partiel, consultez Comprendre les erreurs d'API.