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

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

Chaque objet GoogleAdsError fournit les informations suivantes :

• 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 à 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 qui a généré une erreur.

Exemple d'erreur

Voici un exemple d'erreur au format JSON. Cette erreur indique que le champ name du 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.v24.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"
    }
  ]
}

Consultez notre guide pour en savoir plus sur 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
    );
    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};
  }
}

Capturer des journaux

Pour résoudre les erreurs, capturez les journaux d'erreurs renvoyés par le serveur de l'API Google Ads et inspectez 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 d'API.
2. Examinez la liste errors : examinez chaque GoogleAdsError dans l'objet GoogleAdsFailure. Le error_code et le message vous indiqueront ce qui s'est mal passé.
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 obtenir plus d'informations sur l'erreur et sur la manière de la corriger, consultez la page Erreurs courantes ou la documentation de référence complète sur les codes d'erreur.
5. Ajustez votre requête : en fonction du message d'erreur, corrigez votre requête API. Par exemple, si vous voyez REQUIRED_FIELD_MISSING, assurez-vous de fournir ce champ dans votre requête.
6. Enregistrez 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 le 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 page Erreurs courantes pour obtenir la liste des problèmes fréquents et de leurs solutions.
• Pour en savoir plus sur les techniques avancées de gestion des exceptions, y compris la logique de nouvelle tentative et l'échec partiel, consultez la page Comprendre les erreurs d'API.