Fehlertypen

Wir haben Fehler in die folgenden allgemeinen Kategorien unterteilt:

  • Authentifizierung
  • Fehler, die wiederholt werden können
  • Validierung
  • Synchronisierungsbezogen

Diese Kategorien umfassen zwar nicht alle möglichen Fehler und einige können in mehr als eine Kategorie fallen, sie können jedoch als Ausgangspunkt für die Strukturierung der Fehlerbehandlung Ihrer Anwendung dienen. Weitere Informationen zu bestimmten Fehlern finden Sie in den folgenden Ressourcen:

  • Unter Häufige Fehler finden Sie weitere Informationen zu einem bestimmten Fehler.
  • google.rpc.Status enthält Details zum logischen Fehlermodell, das von der API verwendet wird.
  • Unter Kanonische Fehlercodes finden Sie eine Liste und Erläuterung der kanonischen Fehlercodes, die von gRPC und HTTP im Kontext der Google Ads API definiert werden.

Authentifizierungsfehler

Die Authentifizierung bezieht sich darauf, ob Ihre App von einem Nutzer die Berechtigung erhalten hat, in seinem Namen auf Google Ads zuzugreifen. Die Authentifizierung wird über Anmeldedaten verwaltet, die vom OAuth2-Vorgang generiert werden.

Der häufigste Grund für einen Authentifizierungsfehler, der auf Faktoren außerhalb Ihrer Kontrolle zurückzuführen ist, ist, dass der authentifizierte Nutzer die Berechtigung widerrufen hat, die er Ihrer App erteilt hat, in seinem Namen zu handeln. Wenn Ihre App beispielsweise separate Google Ads-Konten für unabhängige Kunden verwaltet und sich bei der Verwaltung des Kontos eines Kunden separat als dieser Kunde authentifiziert, kann ein Kunde den Zugriff Ihrer App jederzeit widerrufen. Je nachdem, wann Ihr Zugriff widerrufen wurde, gibt die API möglicherweise direkt einen AuthenticationError.OAUTH_TOKEN_REVOKED-Fehler zurück oder die integrierten Anmeldedatenobjekte in den Clientbibliotheken lösen eine Ausnahme für widerrufene Tokens aus. In beiden Fällen können Sie, wenn Ihre App eine Benutzeroberfläche für Ihre Kunden hat, diese bitten, den OAuth2-Vorgang neu zu starten, um die Berechtigung Ihrer App, in ihrem Namen zu handeln, wiederherzustellen.

Wenn Ihr Google Cloud-Projekt nur die Testzugriffsebene hat und versucht, Anfragen an ein Produktionskonto (kein Testkonto) zu senden, gibt die API einen AuthorizationError zurück, dessen Enum-Wert von der API-Version abhängt:

Fehler, die wiederholt werden können

Einige Fehler wie TRANSIENT_ERROR oder INTERNAL_ERROR können auf ein vorübergehendes Problem hinweisen, das sich möglicherweise beheben lässt, wenn Sie die Anfrage nach einer kurzen Pause wiederholen.

Bei von Nutzern initiierten Anfragen besteht eine Strategie darin, sofort einen Fehler in der Benutzeroberfläche anzuzeigen und dem Nutzer die Möglichkeit zu geben, einen Wiederholungsversuch auszulösen. Alternativ kann Ihre App die Anfrage zuerst automatisch wiederholen und den Fehler erst dann in der Benutzeroberfläche anzeigen, wenn eine maximale Anzahl von Wiederholungen oder eine maximale Wartezeit für den Nutzer erreicht wurde.

Bei Anfragen, die im Backend initiiert werden, sollte Ihre App die Anfrage automatisch bis zu einer maximalen Anzahl von Wiederholungen wiederholen.

Verwenden Sie beim Wiederholen von Anfragen eine Richtlinie für exponentiellen Backoff mit zufälligem Jitter. Wenn Sie beispielsweise vor dem ersten Wiederholungsversuch 5 Sekunden warten, können Sie nach dem zweiten 10 Sekunden und nach dem dritten 20 Sekunden warten. Fügen Sie jedem Intervall eine kleine zufällige Verzögerung hinzu, um synchronisierte Wiederholungsspitzen zu vermeiden. Der exponentielle Backoff sorgt dafür, dass Sie die API nicht zu aggressiv aufrufen. Wenn ein Fehler nach mehreren Wiederholungen weiterhin auftritt, protokollieren Sie die request-id aus der Antwort zur Fehlerbehebung.

Validierungsfehler

Zu Validierungsfehlern kommt es nach inakzeptablen Eingaben bei einem Vorgang. Beispiele: PolicyViolationError, DateError, DateRangeError, StringLengthError und UrlFieldError.

Validierungsfehler treten am häufigsten bei vom Nutzer initiierten Anfragen auf, bei denen ein Nutzer eine ungültige Eingabe gemacht hat. In diesen Fällen sollten Sie dem Nutzer eine entsprechende Fehlermeldung basierend auf dem spezifischen API-Fehler anzeigen, den Sie erhalten haben. Sie können Nutzereingaben auch vor dem API-Aufruf auf häufige Fehler prüfen, um die Reaktionsfähigkeit Ihrer Anwendung und die Effizienz Ihrer API-Nutzung zu verbessern. Bei Anfragen vom Backend könnte Ihre Anwendung den fehlgeschlagenen Vorgang einer Warteschlange hinzufügen, damit er von einem menschlichen Operator überprüft werden kann.

Viele Google Ads-Apps verfügen über eine lokale Datenbank zur Speicherung von Google Ads-Objekten. Eine Herausforderung bei diesem Ansatz besteht darin, dass die lokale Datenbank möglicherweise nicht mehr mit den tatsächlichen Objekten in Google Ads synchron ist. Beispielsweise kann ein Nutzer eine Anzeigengruppe direkt in Google Ads löschen, aber die App und die lokale Datenbank wissen nichts von der Änderung und senden weiterhin API-Aufrufe, als ob die Anzeigengruppe noch vorhanden wäre. Diese Synchronisierungsprobleme können sich in einer Vielzahl von Fehlern äußern, z. B. DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD und vielen anderen.

Bei von Nutzern initiierten Anfragen besteht eine Strategie darin, den Nutzer auf ein mögliches Synchronisierungsproblem hinzuweisen, sofort einen Job zu starten, der die relevante Klasse von Google Ads-Objekten abruft und die lokale Datenbank aktualisiert, und den Nutzer dann aufzufordern, die Benutzeroberfläche zu aktualisieren.

Bei Backend-Anfragen enthalten einige Fehler genügend Informationen, damit Ihre App Ihre lokale Datenbank automatisch und schrittweise korrigieren kann. Beispiel: CANNOT_OPERATE_ON_REMOVED_ADGROUPAD sollte dazu führen, dass die Anzeige in Ihrer lokalen Datenbank als entfernt markiert wird. Fehler, die Sie auf diese Weise nicht beheben können, können dazu führen, dass Ihre App einen vollständigeren Synchronisierungsjob startet oder einer Warteschlange zur Überprüfung durch einen menschlichen Operator hinzugefügt wird.

Weiter
API-Fehler verstehen