API-Fehler verstehen

In diesem Leitfaden wird erläutert, wie die Google Ads API Fehler verarbeitet und kommuniziert. Die Struktur und Bedeutung von API-Fehlern zu verstehen ist entscheidend für die Entwicklung robuster Anwendungen, die Probleme wie ungültige Eingaben oder vorübergehende Dienstausfälle problemlos bewältigen können.

Die Google Ads API folgt dem Standardfehlermodell von Google APIs, das auf gRPC-Statuscodes basiert. Jede API-Antwort, die zu einem Fehler führt, enthält ein Status-Objekt mit folgenden Informationen:

• Ein numerischer Fehlercode.
• Eine Fehlermeldung.
• Optionale zusätzliche Fehlerdetails.

Kanonische Fehlercodes

Die Google Ads API verwendet eine Reihe kanonischer Fehlercodes, die von gRPC und HTTP definiert werden. Diese Codes geben einen allgemeinen Hinweis auf den Fehlertyp. Sie sollten immer zuerst diesen numerischen Code prüfen, um die grundlegende Art des Problems zu verstehen.

In der folgenden Tabelle sind die häufigsten Codes zusammengefasst, die bei der Verwendung der Google Ads API auftreten können:

Weitere Informationen zu diesen Codes finden Sie im Leitfaden zum API-Design unter Fehler codes.

Fehlerdetails verstehen

Neben dem Code auf oberster Ebene bietet die Google Ads API spezifischere Fehlerinformationen im Feld details des Status-Objekts. Dieses Feld enthält oft enthält ein GoogleAdsFailure Proto, das eine Liste einzelner GoogleAdsError-Objekte enthält.

Jedes GoogleAdsFailure-Objekt enthält:

• errors: Eine Liste von GoogleAdsError-Objekten, die jeweils einen bestimmten Fehler beschreiben.
• request_id: Eine eindeutige ID für die Anfrage, die für das Debugging und den Support nützlich ist.

Jedes GoogleAdsError-Objekt enthält:

• errorCode: Ein detaillierterer, Google Ads API-spezifischer Fehlercode, z. B. AuthenticationError.NOT_ADS_USER.
• message: Eine für Menschen lesbare Beschreibung des spezifischen Fehlers.
• trigger: Der Wert, der den Fehler verursacht hat, falls zutreffend.
• location: Beschreibt, wo in der Anfrage der Fehler aufgetreten ist, einschließlich Feldpfaden.
• details: Zusätzliche Fehlerdetails, z. B. nicht veröffentlichte Fehlerursachen.

Beispiel für Fehlerdetails

Wenn Sie einen Fehler erhalten, können Sie mit Ihrer Clientbibliothek auf diese Details zugreifen. Ein INVALID_ARGUMENT-Fehler (Code 3) kann beispielsweise GoogleAdsFailure-Details wie die folgenden haben:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

In diesem Beispiel wird trotz des Fehlers auf oberster Ebene INVALID_ARGUMENT in den GoogleAdsFailure-Details angegeben, dass die Felder name und description das Problem verursacht haben und warum (REQUIRED bzw. TOO_SHORT).

Fehlerdetails finden

Wie Sie auf Fehlerdetails zugreifen, hängt davon ab, ob Sie Standard-API-Aufrufe, teilweise Fehler oder Streaming verwenden.

Standard- und Streaming-API-Aufrufe

Wenn ein API-Aufruf ohne Verwendung von teilweisen Fehlern fehlschlägt, einschließlich Streaming Aufrufen, wird das GoogleAdsFailure-Objekt als Teil der nachfolgenden Metadaten in den gRPC-Antwortheadern zurückgegeben. Wenn Sie REST für Standardaufrufe verwenden, GoogleAdsFailure wird in der HTTP-Antwort zurückgegeben. Clientbibliotheken stellen dies in der Regel als Ausnahme mit einem GoogleAdsFailure-Attribut dar.

Teilweise Fehler

Wenn Sie teilweise Fehler verwenden, werden Fehler für fehlgeschlagene Vorgänge im Feld partial_failure_error der Antwort und nicht in den Antwortheadern zurückgegeben. In diesem Fall ist das GoogleAdsFailure in ein google.rpc.Status Objekt in der Antwort eingebettet.

Batch jobs

Bei der Batchverarbeitung können Fehler für einzelne Vorgänge abgerufen werden, indem Sie die Batchjob-Ergebnisse nach Abschluss des Jobs abrufen. Jedes Vorgangsergebnis enthält ein status-Feld mit Fehlerdetails, wenn der Vorgang fehlgeschlagen ist.

Anfrage-ID

Die request-id ist ein eindeutiger String, der Ihre API-Anfrage identifiziert und für die Fehlerbehebung unerlässlich ist.

Sie finden die request-id an mehreren Stellen:

• GoogleAdsFailure: Wenn ein API-Aufruf fehlschlägt und GoogleAdsFailure zurückgegeben wird, enthält er eine request_id.
• Nachfolgende Metadaten: Sowohl bei erfolgreichen als auch bei fehlgeschlagenen Anfragen ist request-id in den nachfolgenden Metadaten der gRPC-Antwort verfügbar.
• Antwortheader: Sowohl bei erfolgreichen als auch bei fehlgeschlagenen Anfragen ist request-id auch in den gRPC- und HTTP-Antwortheadern verfügbar, mit Ausnahme von erfolgreichen Streaming-Anfragen.
• SearchGoogleAdsStreamResponse: Bei Streaming-Anfragen enthält jede SearchGoogleAdsStreamResponse Nachricht ein request_id-Feld.

Wenn Sie Fehler protokollieren oder sich an den Support wenden, geben Sie die request-id an, um die Diagnose von Problemen zu erleichtern.

Best Practices für die Fehlerbehandlung

Implementieren Sie die folgenden Best Practices, um robuste Anwendungen zu entwickeln:

1. Fehlerdetails prüfen: Analysieren Sie immer das details Feld des Status Objekts und suchen Sie insbesondere nach GoogleAdsFailure. Die detaillierten Informationen errorCode, message, und location in GoogleAdsError bieten die nützlichsten Informationen für das Debugging und das Nutzerfeedback.

2. Unterscheiden Sie zwischen Client- und Serverfehlern:

   • Clientfehler: Codes wie INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Diese erfordern Änderungen an der Anfrage oder am Status/den Anmeldedaten Ihrer Anwendung. Wiederholen Sie die Anfrage erst, wenn Sie das Problem behoben haben.
   • Serverfehler: Codes wie UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Diese weisen auf ein vorübergehendes Problem mit dem API-Dienst hin.

3. Implementieren Sie eine Wiederholungsstrategie:

   • Wann wiederholen: Wiederholen Sie den Vorgang nur bei vorübergehenden Serverfehlern wie UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN und ABORTED.
   • Exponentieller Backoff: Verwenden Sie einen exponentiellen Backoff-Algorithmus, um zwischen den Wiederholungsversuchen immer länger zu warten. So vermeiden Sie, dass ein bereits überlasteter Dienst überfordert wird. Warten Sie beispielsweise 1 Sekunde, dann 2 Sekunden, dann 4 Sekunden usw., bis zu einer maximalen Anzahl von Wiederholungsversuchen oder einer maximalen Wartezeit.
   • Jitter: Fügen Sie den Backoff-Verzögerungen eine kleine zufällige Menge „Jitter“ hinzu, um das Problem der „Thundering Herd“ zu vermeiden, bei dem viele Clients gleichzeitig Wiederholungsversuche durchführen.

4. Protokollieren Sie gründlich: Protokollieren Sie die vollständige Fehlerantwort, einschließlich aller Details, insbesondere der Anfrage-ID. Diese Informationen sind für das Debugging und für die Meldung von Problemen an den Google-Support erforderlich.

5. Nutzerfeedback geben: Geben Sie den Nutzern Ihrer Anwendung anhand der spezifischen GoogleAdsError-Codes und ‑Meldungen klares und hilfreiches Feedback. Anstatt nur „Ein Fehler ist aufgetreten“ können Sie beispielsweise „Kampagnenname ist erforderlich“ oder „Die angegebene Anzeigengruppen-ID wurde nicht gefunden“ angeben.

Wenn Sie diese Richtlinien befolgen, können Sie von der Google Ads API zurückgegebene Fehler effektiv diagnostizieren und beheben. So erhalten Sie stabilere und benutzerfreundlichere Anwendungen.