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 ordnungsgemäß verarbeiten können.

Die Google Ads API folgt dem standardmäßigen Google API-Fehlermodell, 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

In der Google Ads API wird eine Reihe von kanonischen Fehlercodes verwendet, 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:

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, in der Regel vom Client. Bedeutet normalerweise, dass der Client nicht mehr wartet. Prüfen Sie die clientseitigen Zeitüberschreitungen.
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 die API daran hindert, die Anfrage zu verarbeiten, z. B. einen fehlerhaften Ressourcennamen oder einen ungültigen Wert. Clientfehler: Prüfen Sie Ihre Anfrageparameter und achten Sie darauf, dass sie den API-Anforderungen entsprechen. Die Fehlerdetails enthalten in der Regel Informationen darüber, welches Argument ungültig war und wie. Verwenden Sie diese Details, um die Anfrage zu korrigieren. Wiederholen Sie den Vorgang nicht, ohne die Anfrage zu korrigieren.
4 504 DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Serverfehler: Oft vorübergehend. Versuchen Sie es mit exponentiellem Backoff noch einmal.
5 404 NOT_FOUND Eine angeforderte Entität, z. B. eine Kampagne oder Anzeigengruppe, wurde nicht gefunden. Clientfehler: Prüfen Sie, ob die Ressourcen, auf die Sie zugreifen möchten, vorhanden sind und ob die IDs korrekt sind. Versuchen Sie es nicht ohne Korrektur noch einmal.
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 bereits 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, die Autorisierung und die Nutzerrollen für das Google Ads-Konto. Versuchen Sie es nicht noch einmal, ohne die Berechtigungen zu klären.
8 429 RESOURCE_EXHAUSTED Entweder ist eine Ressource erschöpft (z. B. weil Sie Ihr Kontingent überschritten haben) oder ein System ist überlastet. Client-/Serverfehler: In der Regel ist Warten erforderlich. Implementieren Sie einen exponentiellen Backoff und reduzieren Sie möglicherweise die Anforderungsrate. Siehe 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 Status ist falsch. Sehen Sie sich die Fehlerdetails an, um den Fehler bei der Vorbedingung zu verstehen. Versuchen Sie es nicht noch einmal, ohne den Status zu korrigieren.
10 409 ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Nebenläufigkeitsproblems wie eines Transaktionskonflikts. Serverfehler: Ein Wiederholungsversuch mit einem kurzen Backoff ist oft sicher.
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: Prüfen Sie die API-Version und die verfügbaren Funktionen. Versuchen Sie es nicht noch einmal.
13 500 INTERNAL Es ist ein interner Fehler aufgetreten. Dies ist ein allgemeiner Sammelbegriff für serverseitige Probleme. Serverfehler: Kann in der Regel mit exponentiellem Backoff wiederholt werden. Wenn das Problem weiterhin besteht, melden Sie es.
14 503 UNAVAILABLE Dieser Dienst ist vorübergehend 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 Nicht wiederherstellbarer Datenverlust oder Datenkorruption. Serverfehler: Selten. Weist auf ein schwerwiegendes Problem hin. Versuchen Sie es nicht noch einmal. Wenn das Problem weiterhin besteht, melden Sie es.
16 401 UNAUTHENTICATED Die Anfrage enthält keine gültigen Authentifizierungsdaten. Clientfehler: Prüfen Sie Ihre Authentifizierungstokens und Anmeldedaten. Versuchen Sie es nicht noch einmal, ohne die Authentifizierung zu korrigieren.

Weitere Informationen zu diesen Codes finden Sie im API-Designleitfaden – Fehlercodes.

Fehlerdetails verstehen

Zusätzlich zum Code auf oberster Ebene bietet die Google Ads API im Feld details des Status-Objekts spezifischere Fehlerinformationen. Dieses Feld enthält häufig 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 aufgetretenen Fehler beschreiben.
  • request_id: Eine eindeutige ID für die Anfrage, die für die Fehlerbehebung und den Support nützlich ist.

Jedes GoogleAdsError-Objekt bietet Folgendes:

Beispiel für Fehlerdetails

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

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

In diesem Beispiel wird trotz des INVALID_ARGUMENT auf oberster 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, Teilfehler oder Streaming verwenden.

Standard- und Streaming-API-Aufrufe

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

Teilweise fehlgeschlagen

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 die GoogleAdsFailure in ein google.rpc.Status-Objekt in der Antwort eingebettet.

Batchjobs

Bei der Batchverarbeitung können Fehler für einzelne Vorgänge nach Abschluss des Jobs durch Aufrufen von BatchJobService.ListBatchJobResults gefunden werden. 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.

Du findest die request-id an mehreren Stellen:

  • GoogleAdsFailure: Wenn ein API-Aufruf fehlschlägt und GoogleAdsFailure zurückgegeben wird, enthält er einen request_id.
  • Nachgestellte Metadaten: Sowohl für erfolgreiche als auch für fehlgeschlagene Anfragen ist request-id in den nachgestellten Metadaten der gRPC-Antwort verfügbar.
  • Antwortheader: Sowohl für erfolgreiche als auch für 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.

Geben Sie beim Protokollieren von Fehlern oder beim Kontaktieren des Supports 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 erstellen:

  1. Fehlerdetails prüfen: Parsen Sie immer das Feld details des Status-Objekts und suchen Sie insbesondere nach GoogleAdsFailure. Die detaillierten error_code, message und location in GoogleAdsError liefern die nützlichsten Informationen für die Fehlerbehebung und das Nutzerfeedback.

  2. Zwischen Client- und Serverfehlern unterscheiden:

    • 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 nicht, ohne das Problem zu beheben.
    • Serverfehler: Codes wie UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Diese weisen auf ein vorübergehendes Problem mit dem API-Dienst hin.

  3. Wiederholungsstrategie implementieren:

    • 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 die Wartezeit zwischen Wiederholungsversuchen schrittweise zu verlängern. So wird vermieden, 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 Gesamtwartezeit.
    • 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, einschließlich aller Details, insbesondere der Anfrage-ID. Diese Informationen sind für die Fehlerbehebung 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 -Nachrichten 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 nutzerfreundlichere Anwendungen.

Zurück
Fehlertypen
Weiter
Häufige Fehler