Fehlertypen

Wir haben Fehler in die folgenden allgemeinen Kategorien unterteilt:

• Authentifizierung
• Wiederholbar
• Validierung
• Synchronisierungsprobleme

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 App 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 für Details zum logischen Fehlermodell, das von der API verwendet wird.

Authentifizierungsfehler

Bei der Authentifizierung geht es darum, ob Ihre App von einem Nutzer die Berechtigung erhalten hat, in seinem Namen auf Google Ads zuzugreifen. Die Authentifizierung wird über Anmeldedaten verwaltet, die über den OAuth2-Ablauf 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 jeweils 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 werfen eine Ausnahme für widerrufene Tokens aus. In beiden Fällen können Ihre Kunden in Ihrer App aufgefordert werden, den OAuth2-Vorgang noch einmal auszuführen, um die Berechtigung Ihrer App wiederherzustellen, in ihrem Namen zu handeln.

Retryable-Fehler

Einige Fehler, z. B. TRANSIENT_ERROR oder INTERNAL_ERROR, können auf ein vorübergehendes Problem hinweisen, das sich durch das Wiederholen der Anfrage nach einer kurzen Pause beheben lässt.

Bei von Nutzern initiierten Anfragen können Sie beispielsweise sofort einen Fehler in Ihrer Benutzeroberfläche 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 dann in der Benutzeroberfläche anzeigen, wenn eine maximale Anzahl von Wiederholungen oder die Gesamtwartezeit des Nutzers erreicht wurde.

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

Verwenden Sie beim Wiederholen von Anfragen eine exponentielle Backoff-Richtlinie. 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 von Nutzern initiierten 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 jeweiligen API-Fehler basiert. Sie können die Nutzereingabe auch auf häufige Fehler prüfen, bevor Sie einen API-Aufruf ausführen. So wird Ihre App reaktionsfähiger und die API-Nutzung effizienter. Bei Anfragen vom Back-End kann Ihre App den fehlgeschlagenen Vorgang einer Warteschlange hinzufügen, die von einem Kundenservicemitarbeiter überprüft wird.

Fehlende Synchronität

Viele Google Ads-Apps verwalten eine lokale Datenbank, um ihre Google Ads-Objekte zu speichern. Ein Nachteil dieses Ansatzes 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 jedoch nicht über die Änderung informiert 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 viele andere.

Bei von Nutzern initiierten Anfragen können Sie den Nutzer beispielsweise über ein mögliches Synchronisierungsproblem informieren, sofort einen Job starten, mit dem die entsprechende Klasse von Google Ads-Objekten abgerufen und die lokale Datenbank aktualisiert wird, und den Nutzer dann auffordern, die Benutzeroberfläche zu aktualisieren.

Bei Back-End-Anfragen enthalten einige Fehler genügend Informationen, damit Ihre App Ihre lokale Datenbank automatisch und inkrementell korrigieren kann. Beispiel: Mit CANNOT_OPERATE_ON_REMOVED_ADGROUPAD sollte Ihre App diese Anzeige in Ihrer lokalen Datenbank als entfernt kennzeichnen. Fehler, die Sie auf diese Weise nicht beheben können, können dazu führen, dass Ihre App einen umfassenderen Synchronisierungsjob startet oder einer Warteschlange hinzugefügt wird, die von einem Kundenservicemitarbeiter überprüft wird.