Typy błędów

Błędy dzielimy na te główne kategorie:

  • Uwierzytelnianie
  • Błędy, które można naprawić, ponawiając próbę
  • Weryfikacja
  • Błędy związane z synchronizacją

Te kategorie nie obejmują wszystkich możliwych błędów, a niektóre z nich mogą pasować do więcej niż 1 kategorii. Mogą one jednak stanowić punkt wyjścia do strukturyzacji obsługi błędów w aplikacji. Więcej informacji o konkretnych błędach znajdziesz w tych materiałach:

  • Typowe błędy – więcej informacji o konkretnym błędzie.
  • google.rpc.Status – szczegóły dotyczące logicznego modelu błędów używanego przez interfejs API.
  • Kanoniczne kody błędów – lista i wyjaśnienie kanonicznych kodów błędów zdefiniowanych przez gRPC i HTTP w kontekście interfejsu Google Ads API.

Błędy uwierzytelniania

Uwierzytelnianie oznacza, że użytkownik przyznał Twojej aplikacji uprawnienia do uzyskiwania dostępu do Google Ads w jego imieniu. Uwierzytelnianie jest zarządzane za pomocą danych logowania generowanych przez przepływ OAuth2.

Najczęstszym powodem wystąpienia błędu uwierzytelniania, na który nie masz wpływu, jest to, że uwierzytelniony użytkownik cofnął uprawnienia przyznane Twojej aplikacji do działania w jego imieniu. Jeśli np. Twoja aplikacja zarządza oddzielnymi kontami Google Ads niezależnych klientów i uwierzytelnia się oddzielnie jako każdy klient podczas zarządzania jego kontem, klient może w każdej chwili cofnąć dostęp do Twojej aplikacji. W zależności od tego, kiedy dostęp został cofnięty, 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 cofnięcia tokena. W obu przypadkach, jeśli Twoja aplikacja ma interfejs użytkownika dla klientów, może poprosić ich o ponowne uruchomienie przepływu OAuth2, aby przywrócić uprawnienia aplikacji do działania w ich imieniu.

Błędy, które można naprawić, ponawiając próbę

Niektóre błędy, np. TRANSIENT_ERROR lub INTERNAL_ERROR, mogą wskazywać na tymczasowy problem, który można rozwiązać, ponawiając próbę wysłania żądania po krótkiej przerwie.

W przypadku żądań inicjowanych przez użytkownika jedną ze strategii jest natychmiastowe wskazanie błędu w interfejsie i umożliwienie użytkownikowi ponowienia próby. Możesz też najpierw automatycznie ponowić próbę wysłania żądania, a dopiero po osiągnięciu maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania użytkownika wyświetlić błąd w interfejsie.

W przypadku żądań inicjowanych w backendzie aplikacja powinna automatycznie ponowić próbę wysłania żądania maksymalną liczbę razy.

Podczas ponawiania prób wysłania żądań stosuj zasadę wzrastającego czasu do ponowienia. Jeśli np. przed pierwszą ponowną próbą zrobisz 5-sekundową przerwę, po drugiej możesz zrobić 10-sekundową, a po trzeciej – 20-sekundową. Wzrastający czas do ponowienia pomaga uniknąć zbyt częstego wywoływania interfejsu API.

Błędy weryfikacji

Błędy weryfikacji wskazują, że dane wejściowe operacji były nieprawidłowe. Na przykład PolicyViolationError, DateError, DateRangeError, StringLengthError i UrlFieldError.

Błędy weryfikacji najczęściej występują w przypadku żądań inicjowanych przez użytkownika, gdy użytkownik wprowadził nieprawidłowe dane. W takich przypadkach należy wyświetlić użytkownikowi odpowiedni komunikat o błędzie na podstawie konkretnego błędu interfejsu API. Przed wywołaniem interfejsu API możesz też sprawdzić dane wejściowe użytkownika pod kątem typowych błędów, co zwiększy responsywność aplikacji i efektywność korzystania z interfejsu API. W przypadku żądań z backendu aplikacja może dodać operację, która się nie powiodła, do kolejki, aby operator mógł ją sprawdzić.

Wiele aplikacji Google Ads utrzymuje lokalną bazę danych do przechowywania obiektów Google Ads. Jednym z problemów związanych z tym podejściem jest to, że lokalna baza danych może przestać 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ą o tym wiedzieć i będą nadal wysyłać wywołania interfejsu API tak, jakby grupa reklam istniała. Te problemy z synchronizacją mogą się objawiać różnymi błędami, takimi jak DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, i wiele innych.

W przypadku żądań inicjowanych przez użytkownika jedną ze strategii jest ostrzeżenie użytkownika o możliwym problemie z synchronizacją, natychmiastowe uruchomienie zadania, które pobiera odpowiednią klasę obiektów Google Ads i aktualizuje lokalną bazę danych, a następnie wyświetlenie użytkownikowi prośby o odświeżenie interfejsu.

W przypadku żądań backendowych niektóre błędy zawierają wystarczająco dużo informacji, aby aplikacja mogła automatycznie i stopniowo poprawiać lokalną bazę danych. Na przykład, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD powinien spowodować, że aplikacja oznaczy tę reklamę jako usuniętą w lokalnej bazie danych. Błędy, których nie można rozwiązać w ten sposób, mogą spowodować, że aplikacja uruchomi bardziej kompleksowe zadanie synchronizacji lub zostanie dodana do kolejki, aby operator mógł ją sprawdzić.

Dalej
Informacje o błędach interfejsu API