Fehlertypen

Wir haben Fehler in die folgenden Kategorien unterteilt:

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

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

  • Unter Häufige Fehler finden Sie weitere Details 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 erfolgt über Anmeldedaten, die vom OAuth2-Vorgang generiert werden.

Der häufigste Grund für einen Authentifizierungsfehler, der auf Faktoren beruht, die außerhalb Ihrer Kontrolle liegen, 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. Wenn Ihre App eine Benutzeroberfläche für Ihre Kunden hat, können Sie sie in beiden Fällen bitten, den OAuth2-Ablauf neu zu starten, um die Berechtigung Ihrer App, in ihrem Namen zu handeln, wiederherzustellen.

Wenn Ihr Google Cloud-Projekt nur die Zugriffsebene für Tests 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 durch erneutes Senden der Anfrage nach einer kurzen Pause behoben werden kann.

Bei nutzerinitiierten Anfragen können Sie in der Benutzeroberfläche sofort einen Fehler anzeigen und dem Nutzer die Möglichkeit geben, einen erneuten Versuch zu starten. Alternativ kann Ihre App die Anfrage zuerst automatisch wiederholen und den Fehler erst 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 Wiederholungsversuchen wiederholen.

Wenn Sie Anfragen wiederholen, verwenden Sie eine Richtlinie für exponentiellen Backoff mit zufälligem Jitter. Wenn Sie beispielsweise vor dem ersten Wiederholungsversuch 5 Sekunden pausieren, könnten Sie nach dem zweiten Wiederholungsversuch 10 Sekunden und nach dem dritten 20 Sekunden pausieren. Fügen Sie jedem Intervall eine kleine zufällige Verzögerung hinzu, um synchronisierte Wiederholungsspitzen zu vermeiden. Mit dem exponentiellen Backoff wird sichergestellt, dass Sie die API nicht zu aggressiv aufrufen. Wenn ein Fehler nach dem Ausschöpfen der 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 sind PolicyViolationError, DateError, DateRangeError, StringLengthError und UrlFieldError.

Validierungsfehler treten am häufigsten bei nutzerinitiierten 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 auch die Nutzereingabe auf häufige Fehler prüfen, bevor Sie einen API-Aufruf starten. So wird Ihre App reaktionsschneller und die API-Nutzung effizienter. Bei Anfragen vom Backend kann Ihre App den fehlgeschlagenen Vorgang in eine Warteschlange einreihen, damit er von einem menschlichen Operator überprüft wird.

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 synchronisiert ist. Ein Nutzer kann beispielsweise eine Anzeigengruppe direkt in Google Ads löschen. Die App und die lokale Datenbank sind sich der Änderung jedoch nicht bewusst und senden weiterhin API-Aufrufe, als ob die Anzeigengruppe 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 vom Nutzer 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 liefern einige Fehler genügend Informationen, damit Ihre App Ihre lokale Datenbank automatisch und inkrementell korrigieren kann. Beispiel: Bei CANNOT_OPERATE_ON_REMOVED_ADGROUPAD sollte Ihre App diese Anzeige in Ihrer lokalen Datenbank als entfernt markieren. Fehler, die Sie auf diese Weise nicht beheben können, können dazu führen, dass Ihre App einen umfassenderen Synchronisierungsvorgang startet oder in eine Warteschlange für die Überprüfung durch einen menschlichen Bediener aufgenommen wird.

Weiter
API-Fehler verstehen