API-Fehler verarbeiten

Wenn Sie eine Anfrage an die Google Ads API senden, kann dies aus verschiedenen Gründen fehlschlagen. Möglicherweise haben Sie ein ungültiges Argument angegeben 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 falsch gelaufen ist.

In dieser Anleitung wird erläutert, wie Sie API-Fehler lesen und behandeln, damit Sie robustere Anwendungen entwickeln können.

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 Fehler code, der den Fehlertyp angibt, z. B. AuthenticationError.NOT_ADS_USER.
• message: Eine für Menschen lesbare Beschreibung der Ursache des Fehlers.
• 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.

Neben der Liste der Fehler enthält GoogleAdsFailure eine requestId, eine eindeutige ID 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 gibt an, dass das Feld name der ad_group mit dem Index 0 in der Anfrage fehlt.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.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};
  }
}

Logs erfassen

Zur Fehlerbehebung müssen Sie die vom Google Ads API-Server zurückgegebenen Fehlerlogs erfassen und deren Inhalt prüfen. Folgen Sie der Anleitung, 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();

Fehlerbehebung

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. Liste errors prüfen: Sehen Sie sich jedes GoogleAdsError im GoogleAdsFailure-Objekt an. Die error_code und message geben Aufschluss darüber, was falsch gelaufen ist.
3. Wert von location prüfen: Das location Feld kann Ihnen helfen, die Stelle in Ihrer Anfrage zu finden, an der das Problem aufgetreten ist.
4. Dokumentation lesen: Informationen zu bestimmten Fehlercodes finden Sie auf der Seite Häufige Fehler oder in der vollständigen Referenz zu Fehlercodes. Dort erfahren Sie mehr über den Fehler und wie Sie ihn beheben können.
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` protokollierenrequest_id: Wenn Sie nicht wissen, wie Sie einen Fehler beheben können, und sich an den Support wenden müssen, fügen Sie die vollständigen Anfrage- und Antwortlogs für die fehlgeschlagene Anfrage bei. Achten Sie darauf, die request_id anzugeben. Mit dieser ID können Google-Techniker die Details der fehlgeschlagenen Anfrage in den Google Ads API-Serverlogs finden und Ihr Problem untersuchen.

Nächste Schritte

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