Typy błędów

Błędy dzielimy na te ogólne kategorie:

  • Uwierzytelnianie
  • Retryable
  • 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ą one stanowić punkt wyjścia do strukturyzacji obsługi błędów w aplikacji. Więcej informacji o poszczególnych błędach znajdziesz w tych materiałach:

  • W sekcji Typowe błędy znajdziesz więcej informacji o konkretnym błędzie.
  • google.rpc.Status, aby dowiedzieć się więcej o modelu błędów logicznych używanym przez interfejs API.
  • Kody błędów kanonicznych – lista i wyjaśnienie kodów błędów kanonicznych zdefiniowanych przez gRPC i HTTP w kontekście interfejsu Google Ads API.

Błędy uwierzytelniania

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

Najczęstszą przyczyną błędu uwierzytelniania wynikającą z czynników, na które nie masz wpływu, jest cofnięcie przez uwierzytelnionego użytkownika uprawnień, które przyznał Twojej aplikacji do działania w jego imieniu. Jeśli na przykład 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 dowolnym momencie cofnąć dostęp do aplikacji. W zależności od tego, kiedy dostęp został cofnięty, interfejs API może bezpośrednio zwracać błąd AuthenticationError.OAUTH_TOKEN_REVOKED lub wbudowane obiekty danych logowania w bibliotekach klienta mogą zgłaszać 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 procesu OAuth2, aby przywrócić uprawnienia aplikacji do działania w ich imieniu.

Błędy, które można ponowić

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

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

W przypadku żądań zainicjowanych na serwerze aplikacja powinna automatycznie ponawiać żądanie maksymalną liczbę razy.

Podczas ponawiania żądań stosuj zasadę wzrastającego czasu do ponowienia. Jeśli na przykład przed pierwszą próbą ponowienia wstrzymasz działanie na 5 sekund, po drugiej próbie możesz wstrzymać je na 10 sekund, a po trzeciej na 20 sekund. Wycofywanie wykładnicze 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 występują najczęściej w przypadku żądań inicjowanych przez użytkowników, w których wprowadzili oni nieprawidłowe dane. W takich przypadkach należy wyświetlić użytkownikowi odpowiedni komunikat o błędzie na podstawie otrzymanego błędu interfejsu API. Przed wywołaniem interfejsu API możesz też sprawdzać dane wejściowe użytkownika pod kątem typowych błędów, dzięki czemu Twoja aplikacja będzie bardziej responsywna, a korzystanie z interfejsu API bardziej efektywne. W przypadku żądań z backendu aplikacja może dodać nieudaną operację do kolejki, aby operator mógł ją sprawdzić.

Wiele aplikacji Google Ads ma lokalną bazę danych, w której przechowuje obiekty Google Ads. Jednym z wyzwań związanych z tym podejściem jest to, że lokalna baza danych może utracić synchronizację z rzeczywistymi obiektami w Google Ads. Użytkownik może na przykład usunąć grupę reklam bezpośrednio w Google Ads, ale aplikacja i lokalna baza danych nie będą wiedzieć o tej zmianie i nadal będą wysyłać wywołania interfejsu API tak, jakby grupa reklam istniała. Problemy z synchronizacją mogą objawiać się różnymi błędami, takimi jak DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD i wieloma innymi.

W przypadku żądań inicjowanych przez użytkownika jedną ze strategii jest powiadomienie go 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ń backendu niektóre błędy zawierają wystarczająco dużo informacji, aby aplikacja mogła automatycznie i stopniowo korygować lokalną bazę danych. Na przykład CANNOT_OPERATE_ON_REMOVED_ADGROUPAD powinno spowodować oznaczenie tej reklamy w aplikacji jako usuniętej w lokalnej bazie danych. Błędy, których nie można rozwiązać w ten sposób, mogą spowodować uruchomienie przez aplikację pełniejszego zadania synchronizacji lub dodanie jej do kolejki do sprawdzenia przez operatora.

Dalej
Informacje o błędach interfejsu API