API-Fehler verstehen

In diesem Leitfaden wird erläutert, wie Fehler in der Google Ads API behandelt und kommuniziert werden. 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 Folgendem:

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

Kanonische Fehlercodes

In der Google Ads API wird eine Reihe kanonischer Fehlercodes verwendet, die von gRPC und HTTP definiert werden. Diese Codes geben einen allgemeinen Hinweis auf den Fehlertyp. Sie sollten diesen numerischen Code immer zuerst 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:

gRPC-Code HTTP-Code Enum-Name Beschreibung Anleitung
0 200 OK Kein Fehler; weist auf einen Erfolg hin. –
1 499 CANCELLED Der Vorgang wurde abgebrochen, üblicherweise vom Client. Das bedeutet in der Regel, dass der Client nicht mehr wartet. Clientseitige Zeitüberschreitungen prüfen
2 500 UNKNOWN Ein unbekannter Fehler ist aufgetreten. Weitere Informationen finden Sie möglicherweise in der Fehlermeldung oder den Fehlerdetails. Als Serverfehler behandeln. Kann oft mit Backoff wiederholt werden.
3 400 INVALID_ARGUMENT Der Client hat ein ungültiges Argument angegeben. Dies weist auf ein Problem hin, das verhindert, dass die API die Anfrage verarbeitet, z. B. ein fehlerhafter Ressourcenname oder ein ungültiger Wert. Clientfehler: Überprüfen Sie die Parameter Ihrer Anfrage und achten Sie darauf, dass sie den API-Anforderungen entsprechen. Die Fehlerdetails enthalten in der Regel Informationen dazu, welches Argument ungültig war und warum. Verwenden Sie diese Details, um die Anfrage zu korrigieren. Wiederholen Sie den Vorgang nur, wenn die Anfrage korrigiert wurde.
4 504 DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Serverfehler: Oft vorübergehend. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
5 404 NOT_FOUND Eine angeforderte Entität, beispielsweise eine Kampagne oder Anzeigengruppe, wurde nicht gefunden. Clientfehler: Prüfen Sie, ob die Ressourcen, auf die Sie zugreifen möchten, vorhanden sind und welche ID sie haben. Wiederholen Sie den Vorgang nicht, ohne das Problem zu beheben.
6 409 ALREADY_EXISTS Die Entität, die der Client erstellen wollte, ist bereits vorhanden. Clientfehler: Vermeiden Sie das Erstellen doppelter Ressourcen. Prüfen Sie, ob die Ressource vorhanden ist, bevor Sie versuchen, sie zu erstellen.
7 403 PERMISSION_DENIED Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs. Clientfehler: Prüfen Sie die Authentifizierung, Autorisierung und Nutzerrollen für das Google Ads-Konto. Wiederholen Sie den Vorgang erst, wenn die Berechtigungen gewährt wurden.
8 429 RESOURCE_EXHAUSTED Entweder ist eine Ressource erschöpft (z. B. haben Sie Ihr Kontingent überschritten) oder ein System ist überlastet. Client-/Serverfehler: In der Regel müssen Sie warten. Implementieren Sie den exponentiellen Backoff und reduzieren Sie möglicherweise die Anfragerate. Weitere Informationen finden Sie unter API-Limits und ‑Kontingente.
9 400 FAILED_PRECONDITION Der Vorgang wurde abgelehnt, weil der Systemzustand nicht für die Ausführung des Vorgangs geeignet ist. Beispiel: Ein Pflichtfeld fehlt. Clientfehler: Die Anfrage ist gültig, aber der state ist falsch. Sehen Sie sich die Fehlerdetails an, um die Ursache für das Scheitern der Vorbedingung zu ermitteln. Wiederholen Sie den Vorgang nicht, ohne den Status zu korrigieren.
10 409 ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Parallelitätsproblems wie eines Transaktionskonflikts. Serverfehler: Oft kann es mit einem kurzen Backoff noch einmal versucht werden.
11 400 OUT_OF_RANGE Beim Vorgang wurde versucht, den gültigen Bereich zu überschreiten. Clientfehler: Korrigieren Sie den Bereich oder Index.
12 501 UNIMPLEMENTED Der Vorgang ist nicht implementiert oder wird von der API nicht unterstützt. Clientfehler: Überprüfen Sie die API-Version und die verfügbaren Funktionen. Wiederholen Sie den Vorgang nicht.
13 500 INTERNAL Es ist ein interner Fehler aufgetreten. Dies ist eine allgemeine Kategorie für serverseitige Probleme. Serverfehler: Kann in der Regel mit exponentiellem Backoff wiederholt werden. Wenn das Problem weiterhin auftritt, melden Sie es.
14 503 UNAVAILABLE Der Dienst ist derzeit nicht verfügbar. Dies ist höchstwahrscheinlich ein vorübergehender Zustand. Serverfehler: Es wird dringend empfohlen, es mit exponentiellem Backoff noch einmal zu versuchen.
15 500 DATA_LOSS Dauerhafter Datenverlust oder Datenkorruption. Serverfehler: Selten. Weist auf ein schwerwiegendes Problem hin. Wiederholen Sie den Vorgang nicht. Wenn das Problem weiterhin auftritt, melden Sie es.
16 401 UNAUTHENTICATED Die Anfrage enthält keine gültigen Anmeldedaten für die Authentifizierung. Clientfehler: Prüfen Sie Ihre Authentifizierungstokens und Anmeldedaten. Wiederholen Sie den Vorgang erst, wenn die Authentifizierung funktioniert.

Weitere Informationen zu diesen Codes finden Sie im Leitfaden zum API-Design – Fehlercodes.

Fehlerdetails nachvollziehen

Zusätzlich zum Code auf oberster Ebene enthält die Google Ads API spezifischere Fehlerinformationen im Feld details des Objekts Status. Dieses Feld enthält oft 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 bietet:

Beispiel für Fehlerdetails

Wenn Sie einen Fehler erhalten, können Sie über Ihre Clientbibliothek auf diese Details zugreifen. Ein INVALID_ARGUMENT (Code 3) könnte beispielsweise die folgenden GoogleAdsFailure-Details haben:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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 der INVALID_ARGUMENT-Informationen auf höchster Ebene 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, Teilausfälle oder Streaming verwenden.

Standard- und Streaming-API-Aufrufe

Wenn ein API-Aufruf ohne Verwendung von Teilausfällen 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 Standardanrufe verwenden, wird GoogleAdsFailure in der HTTP-Antwort zurückgegeben. In Clientbibliotheken wird dies in der Regel als Ausnahme mit dem Attribut GoogleAdsFailure angezeigt.

Teilweiser Fehler

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

Batchjobs

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

Antrags‑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 ein request_id.
  • Nachgestellte Metadaten: Sowohl bei erfolgreichen als auch bei fehlgeschlagenen Anfragen ist request-id in den nachgestellten Metadaten der gRPC-Antwort verfügbar.
  • Antwortheader: Für erfolgreiche und fehlgeschlagene Anfragen ist request-id auch in den gRPC- und HTTP-Antwortheadern verfügbar, mit Ausnahme von erfolgreichen Streaminganfragen.
  • SearchGoogleAdsStreamResponse: Bei Streaminganfragen enthält jede SearchGoogleAdsStreamResponse-Nachricht ein request_id-Feld.

Wenn Sie Fehler protokollieren oder sich an den Support wenden, geben Sie unbedingt die request-id an, damit Probleme leichter diagnostiziert werden können.

Best Practices für die Fehlerbehandlung

Um robuste Anwendungen zu entwickeln, sollten Sie die folgenden Best Practices implementieren:

  1. Fehlerdetails prüfen: Das Feld details des Status-Objekts sollte immer geparst werden, insbesondere nach GoogleAdsFailure. Die detaillierten errorCode, message und location in GoogleAdsError liefern die umsetzbarsten Informationen für das Debugging und Nutzerfeedback.

  2. Client- und Serverfehler unterscheiden:

    • Clientfehler: Codes wie INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Dafür sind Änderungen am Antrag oder am Status/den Anmeldedaten Ihrer Anwendung erforderlich. Wiederholen Sie die Anfrage nicht, ohne das Problem zu beheben.
    • Serverfehler: Codes wie UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Diese deuten auf ein vorübergehendes Problem mit dem API-Dienst hin.

  3. Wiederholungsstrategie implementieren:

    • Wann Sie es noch einmal versuchen sollten: Versuchen Sie es nur bei vorübergehenden Serverfehlern wie UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN und ABORTED noch einmal.
    • Exponentieller Backoff: Verwenden Sie einen exponentiellen Backoff-Algorithmus, um zwischen Wiederholungen immer länger zu warten. So wird verhindert, dass ein bereits überlasteter Dienst überfordert wird. Warten Sie beispielsweise 1 Sekunde, dann 2 Sekunden, dann 4 Sekunden usw., bis Sie die maximale Anzahl an Wiederholungsversuchen oder die maximale Wartezeit erreicht haben.
    • Jitter: Fügen Sie den Backoff-Verzögerungen einen kleinen zufälligen Jitter hinzu, um das „Thundering Herd“-Problem zu vermeiden, bei dem viele Clients gleichzeitig Wiederholungsversuche starten.

  4. Gründlich protokollieren: Protokollieren Sie die vollständige Fehlerantwort mit allen Details, insbesondere die Anfrage-ID. Diese Informationen sind für die Fehlerbehebung und gegebenenfalls für die Meldung von Problemen an den Google-Support unerlässlich.

  5. Nutzerfeedback geben: Geben Sie anhand der spezifischen GoogleAdsError-Codes und ‑Meldungen klares und hilfreiches Feedback an die Nutzer Ihrer Anwendung. Statt nur „Es ist ein Fehler aufgetreten“ können Sie beispielsweise „Der Kampagnenname ist erforderlich“ oder „Die angegebene Anzeigengruppen-ID wurde nicht gefunden“ sagen.

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