Fehlertypen

Wir haben Fehler in die folgenden Kategorien unterteilt:

  • Authentifizierung
  • Wiederholbar
  • 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 für Details zum logischen Fehlermodell, das von der API verwendet wird.
  • Kanonische Fehlercodes für eine Liste und Erklärung 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-Ablauf 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, kann sie sie in beiden Fällen auffordern, den OAuth2-Ablauf neu zu starten, um die Berechtigung Ihrer App, in ihrem Namen zu handeln, wiederherzustellen.

Retryable-Fehler

Einige Fehler, z. B. TRANSIENT_ERROR oder INTERNAL_ERROR, können auf ein vorübergehendes Problem hinweisen, das behoben werden kann, indem Sie die Anfrage nach einer kurzen Pause wiederholen.

Bei nutzerinitiierten Anfragen besteht eine Möglichkeit darin, sofort einen Fehler in der Benutzeroberfläche anzuzeigen und dem Nutzer die Option zu 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.

Verwenden Sie beim Wiederholen von Anfragen eine Richtlinie für exponentiellen Backoff. Warten Sie vor dem zweiten Versuch beispielsweise fünf Sekunden, vor dem dritten zehn Sekunden und vor dem vierten 20 Sekunden. Dadurch wird die API nicht zu häufig aufgerufen.

Validierungsfehler

Zu Validierungsfehlern kommt es nach inakzeptablen Eingaben bei einem Vorgang. Beispiel: 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 anzeigen, die auf dem spezifischen API-Fehler basiert, den Sie erhalten haben. Sie können auch Nutzereingaben auf häufige Fehler prüfen, bevor Sie einen API-Aufruf ausführen. So wird Ihre App reaktionsschneller und die API-Nutzung effizienter. Bei Anfragen vom Backend kann Ihre App den fehlgeschlagenen Vorgang einer Warteschlange hinzufügen, damit er von einem menschlichen Bediener überprüft wird.

In vielen Google Ads-Apps wird eine lokale Datenbank zum Speichern der Google Ads-Objekte verwendet. 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 könnte beispielsweise eine Anzeigengruppe direkt in Google Ads löschen, aber die App und die lokale Datenbank sind sich der Änderung 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 nutzerinitiierten Anfragen können Sie den Nutzer auf ein mögliches Synchronisierungsproblem hinweisen, sofort einen Job starten, der die relevante Klasse von Google Ads-Objekten abruft und die lokale Datenbank aktualisiert, und den Nutzer dann auffordern, die Benutzeroberfläche zu aktualisieren.

Bei Back-End-Anfragen liefern einige Fehler genügend Informationen, damit Ihre App Ihre lokale Datenbank automatisch und inkrementell korrigieren kann. Beispiel: CANNOT_OPERATE_ON_REMOVED_ADGROUPAD sollte dazu führen, dass Ihre App diese Anzeige in Ihrer lokalen Datenbank als entfernt markiert. Fehler, die Sie auf diese Weise nicht beheben können, können dazu führen, dass Ihre App einen vollständigeren Synchronisierungsvorgang startet oder in eine Warteschlange für die Überprüfung durch einen menschlichen Operator aufgenommen wird.

Weiter
API-Fehler verstehen