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, ale mogą one służyć jako punkt wyjścia do ustrukturyzowania obsługi błędów w aplikacji. Więcej informacji o konkretnych 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łędu w logice używanym przez interfejs API.
  • Kanoniczne kody błędów zawiera listę i objaśnienia kanonicznych kodów błędów zdefiniowanych przez gRPC i HTTP w kontekście interfejsu Google Ads API.

Błędy uwierzytelniania

Uwierzytelnianie odnosi się do tego, czy aplikacja otrzymała od użytkownika uprawnienia do dostępu do Google Ads w jego imieniu. Uwierzytelnianie jest zarządzane za pomocą danych logowania wygenerowanych przez proces OAuth2.

Najczęstszą przyczyną błędu uwierzytelniania, który wynika z czynników niezależnych od Ciebie, 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ę osobno jako każdy klient podczas zarządzania jego kontem, klient może w każdej chwili cofnąć dostęp aplikacji. W zależności od tego, kiedy dostęp został unieważniony, 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żnienia tokena. W obu przypadkach, jeśli 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.

Podobnie, jeśli Twój projekt w chmurze Google Cloud ma tylko poziom dostępu Test i próbuje wysyłać żądania do konta produkcyjnego (nie testowego), interfejs API zwraca błąd AuthorizationError, którego wartość typu wyliczeniowego zależy od wersji interfejsu API:

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

Niektóre błędy, takie jak 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ń inicjowanych przez użytkownika jedną ze strategii jest natychmiastowe wskazanie błędu w interfejsie i umożliwienie użytkownikowi ponownej próby. Możesz też skonfigurować aplikację tak, aby najpierw automatycznie ponawiała żądanie, a błąd wyświetlała w interfejsie dopiero po osiągnięciu maksymalnej liczby prób lub łącznego czasu oczekiwania użytkownika.

W przypadku żądań inicjowanych w backendzie aplikacja powinna automatycznie ponawiać żądanie do maksymalnej liczby ponownych prób.

Podczas ponawiania żądań używaj zasad wzrastającego czasu do ponowienia z losowym jitterem. Jeśli na przykład przed pierwszą próbą odczekasz 5 sekund, przed drugą możesz odczekać 10 sekund, a przed trzecią – 20 sekund. Do każdego interwału dodaj niewielkie losowe opóźnienie, aby zapobiec skokom liczby prób. Wzrastający czas do ponowienia pomaga uniknąć zbyt agresywnego wywoływania interfejsu API. Jeśli błąd będzie się powtarzał po wyczerpaniu prób, zarejestruj request-id z odpowiedzi, aby rozwiązać problem.

Błędy weryfikacji

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

Błędy weryfikacji występują najczęściej w żądaniach inicjowanych przez użytkownika, gdy użytkownik wprowadził nieprawidłowe dane wejściowe. W takich przypadkach należy wyświetlić użytkownikowi odpowiedni komunikat o błędzie na podstawie konkretnego błędu interfejsu API. Możesz też sprawdzać dane wejściowe użytkownika pod kątem typowych błędów przed wywołaniem interfejsu API, co zwiększy szybkość działania aplikacji i wydajność 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 przechowuje obiekty Google Ads w lokalnej bazie danych. Jednym z problemów związanych z tym podejściem jest to, że lokalna baza danych może nie 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 będą nadal 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, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD i wiele innych.

W przypadku żądań inicjowanych 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 i aktualizuje lokalną bazę danych, a następnie poproszenie użytkownika o odświeżenie interfejsu.

W przypadku żądań backendu niektóre błędy dostarczają 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ć, że aplikacja oznaczy tę reklamę jako usuniętą w lokalnej bazie danych. Błędy, których nie można obsłużyć w ten sposób, mogą spowodować, że aplikacja uruchomi bardziej kompletne zadanie synchronizacji lub zostanie dodana do kolejki, aby operator mógł ją sprawdzić.

Dalej
Informacje o błędach interfejsu API