Typy błędów

Błędy podzieliliśmy na te ogólne kategorie:

  • Uwierzytelnianie
  • Błędy, które można ponowić
  • Walidacja
  • 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ż jednej kategorii. Mogą one jednak 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:

  • Więcej informacji o konkretnym błędzie znajdziesz w sekcji Typowe błędy.
  • google.rpc.Status zawiera szczegółowe informacje o modelu błędów logicznych używanym przez interfejs API.
  • Kanoniczne kody błędów zawiera listę 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, czy użytkownik przyznał Twojej 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ęstsza przyczyna błędu uwierzytelniania wynikająca z czynników, na które nie masz wpływu, to 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 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 procesu OAuth2, aby przywrócić uprawnienia aplikacji do działania w ich imieniu.

Jeśli Twój projekt w chmurze Google ma tylko poziom dostępu testowego i próbuje wysyłać żądania do konta produkcyjnego (innego niż testowe), interfejs API zwraca błąd AuthorizationError, którego wartość wyliczeniowa zależy od wersji interfejsu API:

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 próbę 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 backendzie aplikacja powinna automatycznie ponawiać żądanie maksymalną liczbę razy.

Podczas ponawiania żądań używaj strategii wzrastającego czasu do ponowienia z losowym rozrzutem. 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. Dodaj do każdego interwału niewielkie losowe opóźnienie, aby zapobiec zsynchronizowanym skokom ponawiania. Wzrastający czas do ponowienia pomaga uniknąć zbyt częstego wywoływania interfejsu API. Jeśli po wyczerpaniu liczby ponownych prób błąd nadal występuje, zarejestruj wartość request-id z odpowiedzi, aby rozwiązać problem.

Błędy weryfikacji

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

.

Błędy weryfikacji najczęściej występują w przypadku żądań zainicjowanych przez użytkownika, w których podał on nieprawidłowe dane wejściowe. 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, co zwiększy szybkość reakcji aplikacji i efektywność korzystania z interfejsu API. W przypadku żądań z backendu aplikacja może dodać nieudaną operację do kolejki, aby operator mógł ją sprawdzić.

Wiele aplikacji Google Ads prowadzi 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 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ą się objawiać różnymi błędami, np. 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 poprawiać lokalną bazę danych. Na przykład CANNOT_OPERATE_ON_REMOVED_ADGROUPAD powinno spowodować oznaczenie reklamy jako usuniętej w lokalnej bazie danych aplikacji. Błędy, których nie możesz obsłużyć 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