API-Fehler verarbeiten

Wenn Sie eine Anfrage an die Google Ads API senden, kann sie aus verschiedenen Gründen fehlschlagen. Möglicherweise haben Sie ein ungültiges Argument angegeben oder in Ihrem Konto wurde 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 behandeln können, um robustere Anwendungen zu entwickeln.

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 bietet:

• error_code: Ein bestimmter Fehlercode, der den Fehlertyp angibt, z. B. AuthenticationError.NOT_ADS_USER.
• message: Eine für Menschen lesbare Beschreibung des Grunds für den Fehler.
• 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, eine eindeutige Kennzeichnung für die API-Anfrage, die zu einem Fehler geführt hat.

Beispiel für Fehlermeldung

Hier sehen Sie 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.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"
    }
  ]
}

Weitere Informationen zu API-Fehlern finden Sie in unserem Leitfaden.

Beispiele für Clientbibliotheken

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

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

Protokolle erfassen

Um Fehler zu beheben, erfassen Sie die vom Google Ads API-Server zurückgegebenen Fehlerprotokolle und prüfen Sie deren Inhalt. Folgen Sie der Anleitung unten, um die Protokollierung zu aktivieren und API-Logs zu erfassen.

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

Fehlerbehandlung

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 jedes GoogleAdsError-Objekt im GoogleAdsFailure-Objekt an. Die error_code und message geben Aufschluss darüber, was schiefgelaufen ist.
3. location-Wert prüfen: Mit dem Feld location können Sie herausfinden, an welcher Stelle in Ihrer Anfrage das Problem aufgetreten ist.
4. Dokumentation aufrufen: Weitere Informationen zu bestimmten Fehlercodes finden Sie auf der Seite Häufige Fehler oder in der vollständigen Referenz zu Fehlercodes.
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 herausfinden können, wie Sie einen Fehler beheben, und den Support kontaktieren müssen, fügen Sie die vollständigen Anfrage- und Antwortprotokolle für die fehlgeschlagene Anfrage ein. Achten Sie darauf, dass das Flag request_id angegeben ist. Anhand dieser ID können Google-Techniker die Details der fehlgeschlagenen Anfrage in den Serverprotokollen der Google Ads API finden und Ihr Problem untersuchen.

Nächste Schritte

• Unter Häufige Fehler finden Sie eine Liste häufig auftretender Probleme und deren Lösungen.
• Weitere Informationen zu erweiterten Techniken zur Fehlerbehandlung, einschließlich Wiederholungslogik und Teilausfall, finden Sie unter API-Fehler verstehen.