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 schiefgelaufen ist.

In diesem Leitfaden wird erläutert, wie Sie API-Fehler lesen und beheben können, 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 zu verstehen, warum der Fehler aufgetreten ist.

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 menschenlesbare 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.

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.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.

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
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors 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 "
            f"'{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

Zur Fehlerbehebung müssen Sie die vom Google Ads API-Server zurückgegebenen Fehlerprotokolle erfassen und ihren Inhalt prüfen. Folgen Sie der Anleitung, um die Protokollierung zu aktivieren und API-Protokolle 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();

Fehler beheben

Wenn ein Fehler auftritt, gehen Sie so vor:

1. Ausnahme abfangen und Protokolle erfassen: Fangen Sie zuerst die Ausnahmen ab und erfassen Sie optional die API-Protokolle.
2. Liste errors prüfen: Sehen Sie sich jedes GoogleAdsError-Objekt im GoogleAdsFailure-Objekt an. Der error_code und message geben an, was schiefgelaufen ist.
3. Wert 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: Weitere Informationen zum Fehler und zur Behebung finden Sie unter Häufige Fehler oder in der vollständigen Referenz zu Fehlercodes.
5. Anfrage anpassen: Korrigieren Sie Ihre API Anfrage anhand der Fehlermeldung. Wenn beispielsweise REQUIRED_FIELD_MISSING angezeigt wird, müssen Sie dieses Feld in Ihrer Anfrage angeben.
6. Protokollieren Sie die request_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 Antwortprotokolle für die fehlgeschlagene Anfrage bei. Achten Sie darauf, die request_id anzugeben. Diese ID hilft Google-Entwicklern, die Details der fehlgeschlagenen Anfrage in den Google Ads API-Server-Logs zu finden und Ihr Problem zu 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 der Logik für Wiederholungsversuche und teilweiser Fehler, finden Sie unter API-Fehler verstehen.