Błędy są podzielone na następujące ogólne kategorie:
- Uwierzytelnianie
- Można spróbować ponownie
- Weryfikacja
- Związane z synchronizacją
Chociaż te kategorie nie obejmują wszystkich możliwych błędów, a niektóre mogą pasować do więcej niż jednej kategorii, mogą posłużyć za punkt wyjścia do uporządkowania struktury obsługi błędów w aplikacji. Więcej informacji o konkretnych błędach znajdziesz w sekcji Typowe błędy.
Błędy uwierzytelniania
Uwierzytelnianie wskazuje, czy użytkownik przyznał aplikacji uprawnienia dostępu do Google Ads w jego imieniu. Uwierzytelnianiem jest zarządzane za pomocą danych logowania generowanych przez przepływ OAuth2.
Najczęstszą przyczyną błędu uwierzytelniania jest to, że uwierzytelniony użytkownik unieważnił uprawnienia aplikacji do działania w jego imieniu. Jeśli na przykład Twoja aplikacja zarządza osobnymi kontami Google Ads niezależnych klientów i uwierzytelnia się oddzielnie jako każdy klient podczas zarządzania kontem danego klienta, może on w każdej chwili odebrać jej dostęp do aplikacji. W zależności od tego, kiedy dostęp został anulowany, interfejs API może bezpośrednio zwrócić błąd AuthenticationError.OAUTH_TOKEN_REVOKED lub wbudowane obiekty danych logowania w bibliotekach klienta mogą zgłosić wyjątek unieważniony tokenem. W obu przypadkach, jeśli Twoja aplikacja ma interfejs dla klientów, możesz poprosić ich o ponowne uruchomienie przepływu OAuth2, aby odzyskać uprawnienia aplikacji do działania w ich imieniu.
Błędy, które można ponawiać
Niektóre błędy, takie jak TRANSIENT_ERROR lub INTERNAL_ERROR, mogą wskazywać na tymczasowy problem, który można rozwiązać przez ponowienie próby przesłania żądania po krótkiej przerwie.
W przypadku żądań zainicjowanych przez użytkownika jedną ze strategii jest natychmiastowe powiadomienie o błędzie w interfejsie i udostępnienie użytkownikowi opcji ponowienia próby. Możesz też najpierw automatycznie przesłać żądanie, ale błąd będzie widoczny w interfejsie dopiero po osiągnięciu maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania użytkownika.
W przypadku żądań zainicjowanych przez backend aplikacja powinna automatycznie ponawiać żądania maksymalnie do maksymalnej liczby takich prób.
Przy ponownych żądaniach używaj zasady wzrastającego czasu do ponowienia. Jeśli na przykład przerwiesz 5 sekund przed pierwszą próbą, możesz zrobić to po 10 sekundach po drugiej i 20 sekundach po trzecim. Wykładniczy czas do ponowienia zapewnia, że nie będziesz wywoływać interfejsu API zbyt intensywnie.
Błędy weryfikacji
Błędy weryfikacji wskazują, że dane wejściowe operacji są niedopuszczalne.
Przykłady: PolicyViolationError,
DateError,
DateRangeError,
StringLengthError i UrlFieldError.
Błędy weryfikacji występują najczęściej w przypadku żądań zainicjowanych przez użytkownika, gdy użytkownik wpisał nieprawidłowe dane wejściowe. W takich przypadkach należy przekazać użytkownikowi komunikat o błędzie odpowiadający konkretnemu komunikatowi o błędzie interfejsu API. Przed wywołaniem interfejsu API możesz też sprawdzać dane wejściowe użytkowników pod kątem typowych błędów, co zwiększa elastyczność aplikacji i efektywniejsze korzystanie z interfejsu API. W przypadku żądań z backendu aplikacja może dodać nieudaną operację do kolejki, którą operator musi sprawdzić.
Błędy związane z synchronizacją
Wiele aplikacji Google Ads korzysta z lokalnej bazy danych, w której przechowywane są obiekty Google Ads. Jednym z problemów związanych z tym podejściem jest fakt, że lokalna baza danych może nie być zsynchronizowana z rzeczywistymi obiektami w Google Ads. Użytkownik może np. usunąć grupę reklam bezpośrednio w Google Ads, ale aplikacja i lokalna baza danych nie będą świadomi tej zmiany i nadal będą wysyłać wywołania interfejsu API tak, jakby grupa reklam istniała. Te problemy z synchronizacją mogą objawiać się różnymi błędami, takimi jak DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP czy CANNOT_OPERATE_ON_REMOVED_ADGROUPAD.
W przypadku żądań zainicjowanych przez użytkownika jedną ze strategii jest powiadomienie użytkownika o możliwym problemie z synchronizacją, natychmiastowe uruchomienie zadania, które pobiera odpowiednią klasę obiektów Google Ads, aktualizuje lokalną bazę danych, a następnie prosi użytkownika o odświeżenie interfejsu.
W przypadku żądań backendu niektóre błędy zawierają wystarczającą ilość informacji, aby aplikacja automatycznie i stopniowo poprawiała lokalną bazę danych. Na przykład reguła CANNOT_OPERATE_ON_REMOVED_ADGROUPAD powinna spowodować oznaczenie tej reklamy jako usuniętej z lokalnej bazy danych. Błędy, których nie możesz obsłużyć w ten sposób, mogą spowodować uruchomienie przez aplikację bardziej kompletnego zadania synchronizacji lub dodanie jej do kolejki do sprawdzenia przez pracownika.