API-Fehler verarbeiten

Wenn Sie eine Anfrage an die Google Ads API senden, kann sie aus verschiedenen Gründen fehlschlagen. Beispielsweise könnten Sie ein ungültiges Argument angeben oder Ihr Konto hat das Limit für die Erstellung neuer Kampagnen erreicht. In solchen Fällen gibt die API einen Fehler zurück, um Sie darüber zu informieren, was schiefgelaufen ist.

In diesem Leitfaden wird erläutert, wie Sie API-Fehler lesen und verarbeiten, um robustere Anwendungen zu erstellen.

Fehlerstruktur

Wenn Sie eine unserer Clientbibliotheken verwenden, werden API-Fehler als Ausnahmen angezeigt. Diese Ausnahmen enthalten Details, die Ihnen helfen, die Ursache des Fehlers zu verstehen.

Die Google Ads API gibt Fehlerinformationen in einem Standardformat zurück. Wenn ein Fehler auftritt, enthält die Antwort ein GoogleAdsFailure-Objekt. Dieses Objekt enthält eine Liste einzelner GoogleAdsError-Objekte, die jeweils einen bestimmten Fehler beschreiben.

Jedes GoogleAdsError-Objekt enthält Folgendes:

  • error_code: Ein bestimmter Fehlercode, der den Fehlertyp angibt, z. B. AuthenticationError.NOT_ADS_USER.
  • message: Eine menschenlesbare Beschreibung, warum der Fehler aufgetreten ist.
  • trigger: Der Wert, der den Fehler verursacht hat, z. B. „1234“.
  • location: Details dazu, welcher Teil der Anfrage den Fehler verursacht hat, z. B. ein bestimmter Feldname.

Zusätzlich zur Liste der Fehler enthält GoogleAdsFailure eine requestId, die eine eindeutige Kennung für die API-Anfrage ist, die zu einem Fehler geführt hat.

Beispiel für Fehlermeldung

Hier ist ein Beispiel für einen Fehler im JSON-Format. Dieser Fehler weist darauf hin, dass das Feld name des ad_group am Index 0 in der Anfrage fehlt.

{
  "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"
    }
  ]
}

Weitere Informationen zu API-Fehlern finden Sie unter API-Fehler verstehen.

Beispiele für Clientbibliotheken

Im folgenden Abschnitt wird beschrieben, wie Fehler in verschiedenen Clientbibliotheken behandelt werden.

Java

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);
  }
}

C#

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}");
    }
}

PHP

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
        );
    }
}

Python

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}'."
        )

Ruby

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

Perl

# 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};
  }
}

Protokolle erstellen

Wenn Sie Fehler beheben möchten, erfassen Sie die Fehlerprotokolle, die vom Google Ads API-Server zurückgegeben werden, und prüfen Sie deren Inhalt. Folgen Sie der Anleitung unten, um das Logging zu aktivieren und API-Logs zu erfassen.

Java

Eine Anleitung finden Sie im Logging-Leitfaden für die Java-Clientbibliothek.

C#

Sie können das Logging initialisieren, indem Sie die folgende Zeile in Ihre Main-Methode einfügen, bevor Sie API-Aufrufe ausführen. So wird sichergestellt, dass die Bibliothek Logs für alle API-Aufrufe generiert, die von Ihrer Anwendung ausgeführt werden.

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);

Weitere Optionen finden Sie im Leitfaden zum Logging in der .NET-Bibliothek.

PHP

Sie können die Logging-Konfiguration in der Datei google_ads_php.ini Ihrer Clientbibliothek festlegen. Setzen Sie logLevel auf NOTICE, um mit der Erfassung der detaillierten Fehlerlogs zu beginnen.

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

Eine Anleitung finden Sie im Leitfaden zur Protokollierung der PHP-Clientbibliothek.

Python

Sie können die Logging-Konfiguration in der Datei google-ads.yaml Ihrer Clientbibliothek festlegen. Legen Sie die Logging-Ebene auf DEBUG fest, um die detaillierten Fehlerlogs zu erfassen.

Weitere Optionen finden Sie im Logging-Leitfaden für die Python-Bibliothek.

Ruby

Sie können die Logging-Konfiguration in der Datei google_ads_config.rb Ihrer Clientbibliothek festlegen. Legen Sie die Logging-Ebene auf INFO fest, um mit der Erfassung der detaillierten Fehlerlogs zu beginnen.

Weitere Optionen finden Sie im Logging-Leitfaden für die Ruby-Bibliothek.

Perl

Fügen Sie die folgende Zeile in Ihr Perl-Script ein, bevor Sie API-Aufrufe ausführen, um das Logging zu initialisieren.

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

Weitere Optionen finden Sie im Logging-Leitfaden für die Perl-Bibliothek.

curl

curl gibt die fehlgeschlagenen Antworten standardmäßig in stderr aus.

Fehler beheben

Wenn ein Fehler auftritt, gehen Sie so vor:

  1. Ausnahme abfangen und Logs erfassen: Fangen Sie zuerst die Ausnahmen ab und erfassen Sie optional die API-Logs.
  2. errors-Liste prüfen: Sehen Sie sich die einzelnen GoogleAdsError im GoogleAdsFailure-Objekt an. Die error_code und message geben Aufschluss darüber, was schiefgelaufen ist.
  3. Wert location prüfen: Das Feld location kann Ihnen helfen, genau festzustellen, wo in Ihrer Anfrage das Problem aufgetreten ist.
  4. Dokumentation lesen: Weitere Informationen zu bestimmten Fehlercodes und deren Behebung finden Sie auf der Seite Häufige Fehler oder in der vollständigen Fehlercode-Referenz.
  5. Anfrage anpassen: Korrigieren Sie Ihre API-Anfrage anhand der Fehlermeldung. Wenn Sie beispielsweise REQUIRED_FIELD_MISSING sehen, müssen Sie dieses Feld in Ihrer Anfrage angeben.
  6. request_id protokollieren: Wenn Sie nicht wissen, wie Sie einen Fehler beheben können, und den Support kontaktieren müssen, fügen Sie die vollständigen Anfrage- und Antwortprotokolle für die fehlgeschlagene Anfrage bei. Geben Sie die request_id an. Anhand dieser ID können Google-Entwickler die Details der fehlgeschlagenen Anfrage in den Serverprotokollen der Google Ads API finden und das Problem untersuchen.

Nächste Schritte

  • Eine Liste häufiger Probleme und ihrer Lösungen finden Sie unter Häufige Fehler.
  • Weitere Informationen zu fortgeschrittenen Techniken zur Fehlerbehandlung, einschließlich Wiederholungslogik und Teilfehlern, finden Sie unter API-Fehler verstehen.
Zurück
Schnelleinstieg
Weiter
Häufige Fehler