Informacje o błędach interfejsu API

Z tego przewodnika dowiesz się, jak interfejs Google Ads API obsługuje błędy i jak o nich informuje. Zrozumienie struktury i znaczenia błędów interfejsu API jest kluczowe do tworzenia niezawodnych aplikacji, które mogą sprawnie radzić sobie z problemami, od nieprawidłowych danych wejściowych po tymczasową niedostępność usługi.

Interfejs Google Ads API jest zgodny ze standardowym modelem błędów interfejsów API Google, który jest oparty na kodach stanu gRPC. Każda odpowiedź interfejsu API, która powoduje błąd, zawiera obiekt Status, który zawiera:

  • Kod błędu w postaci liczby.
  • komunikat o błędzie,
  • Opcjonalne dodatkowe szczegóły błędu.

Kody błędów kanonicznych

Interfejs Google Ads API używa zestawu kanonicznych kodów błędów zdefiniowanych przez gRPC i HTTP. Te kody zawierają ogólne informacje o rodzaju błędu. Zawsze najpierw sprawdzaj ten kod numeryczny, aby zrozumieć podstawową naturę problemu.

W tabeli poniżej znajdziesz podsumowanie najczęstszych kodów, które możesz napotkać podczas korzystania z interfejsu Google Ads API:

Kod gRPC Kod HTTP Nazwa typu wyliczeniowego Opis Wskazówki
0 200 OK Brak błędu; oznacza powodzenie. Nie dotyczy
1 499 CANCELLED Operacja została anulowana, zwykle przez klienta. Zwykle oznacza to, że klient przestał czekać. Sprawdź limity czasu po stronie klienta.
2 500 UNKNOWN Wystąpił nieznany błąd. Więcej szczegółów znajdziesz w komunikacie o błędzie lub w szczegółach. Traktuj jako błąd serwera. Często można ponowić próbę z wycofywaniem.
3 400 INVALID_ARGUMENT Klient podał nieprawidłowy argument. Wskazuje to problem, który uniemożliwia interfejsowi API przetworzenie żądania, np. nieprawidłową nazwę zasobu lub nieprawidłową wartość. Błąd klienta: sprawdź parametry żądania i upewnij się, że spełniają one wymagania interfejsu API. Szczegóły błędu zwykle zawierają informacje o tym, który argument był nieprawidłowy i w jaki sposób. Wykorzystaj te informacje, aby poprawić żądanie. Nie ponawiaj próby bez naprawienia żądania.
4 504 DEADLINE_EXCEEDED Termin upłynął przed wykonaniem operacji. Błąd serwera: często przejściowy. Rozważ ponowienie próby z zastosowaniem wzrastającego czasu do ponowienia.
5 404 NOT_FOUND Nie znaleziono żądanego elementu, np. kampanii lub grupy reklam. Błąd klienta: sprawdź, czy zasoby, do których próbujesz uzyskać dostęp, istnieją i czy ich identyfikatory są prawidłowe. Nie próbuj ponownie bez poprawienia.
6 409 ALREADY_EXISTS Encja, którą próbował utworzyć klient, już istnieje. Błąd klienta: unikaj tworzenia zduplikowanych zasobów. Zanim spróbujesz utworzyć zasób, sprawdź, czy on istnieje.
7 403 PERMISSION_DENIED Element wywołujący nie ma uprawnień do wykonania określonej operacji. Błąd klienta: sprawdź uwierzytelnianie, autoryzację i role użytkowników na koncie Google Ads. Nie próbuj ponownie bez rozwiązania problemu z uprawnieniami.
8 429 RESOURCE_EXHAUSTED Zasób został wyczerpany (np. przekroczono limit) lub system jest przeciążony. Błąd klienta/serwera: zwykle wymaga odczekania. Wdróż wzrastający czas do ponowienia i potencjalnie zmniejsz szybkość wysyłania żądań. Zobacz Limity interfejsów API.
9 400 FAILED_PRECONDITION Operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania. Na przykład brakuje wymaganego pola. Błąd klienta: żądanie jest prawidłowe, ale stan jest nieprawidłowy. Sprawdź szczegóły błędu, aby poznać przyczynę niepowodzenia warunku wstępnego. Nie próbuj ponownie bez poprawienia stanu.
10 409 ABORTED Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. konfliktu transakcji. Błąd serwera: często można ponowić próbę z krótkim wycofaniem.
11 400 OUT_OF_RANGE Operacja została podjęta poza prawidłowym zakresem. Błąd klienta: popraw zakres lub indeks.
12 501 UNIMPLEMENTED Operacja nie jest zaimplementowana lub nie jest obsługiwana przez interfejs API. Błąd klienta: sprawdź wersję interfejsu API i dostępne funkcje. Nie próbuj ponownie.
13 500 INTERNAL Wystąpił błąd wewnętrzny. Jest to ogólna kategoria problemów po stronie serwera. Błąd serwera: zwykle można ponowić próbę z wzrastającym czasem do ponowienia. Jeśli problem będzie się powtarzał, zgłoś go.
14 503 UNAVAILABLE Usługa jest obecnie niedostępna. Jest to najprawdopodobniej stan przejściowy. Błąd serwera: zdecydowanie zalecamy ponowienie próby z wzrastającym czasem do ponowienia.
15 500 DATA_LOSS Nieodwracalna utrata lub uszkodzenie danych. Błąd serwera: rzadki. Wskazuje poważny problem. Nie próbuj ponownie. Jeśli problem będzie się powtarzał, zgłoś go.
16 401 UNAUTHENTICATED Żądanie nie ma prawidłowych danych uwierzytelniających. Błąd klienta: sprawdź tokeny uwierzytelniające i dane logowania. Nie próbuj ponownie bez naprawienia uwierzytelniania.

Więcej informacji o tych kodach znajdziesz w przewodniku API Design Guide – kody błędów.

Szczegóły błędu

Oprócz kodu najwyższego poziomu interfejs Google Ads API udostępnia bardziej szczegółowe informacje o błędach w polu details obiektu Status. To pole często zawiera protokół GoogleAdsFailure, który zawiera listę poszczególnych obiektów GoogleAdsError.

Każdy obiekt GoogleAdsFailure zawiera:

  • errors: lista obiektów GoogleAdsError, z których każdy zawiera szczegółowe informacje o konkretnym błędzie, który wystąpił.
  • request_id: unikalny identyfikator żądania, przydatny do debugowania i wsparcia;

Każdy obiekt GoogleAdsError zawiera:

Przykład szczegółów błędu

Gdy otrzymasz błąd, biblioteka klienta umożliwi Ci dostęp do tych szczegółów. Na przykład INVALID_ARGUMENT (kod 3) może mieć takie GoogleAdsFailure szczegóły:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

W tym przykładzie pomimo ikony najwyższego poziomu INVALID_ARGUMENT szczegóły GoogleAdsFailure informują, że problem spowodowały pola name i description oraz dlaczego (REQUIRED i TOO_SHORT).

Znajdź szczegóły błędu

Sposób uzyskiwania dostępu do szczegółów błędu zależy od tego, czy używasz standardowych wywołań interfejsu API, częściowego niepowodzenia czy przesyłania strumieniowego.

Standardowe i strumieniowe wywołania interfejsu API

Gdy wywołanie interfejsu API zakończy się niepowodzeniem bez użycia częściowego niepowodzenia, w tym wywołania przesyłania strumieniowego, obiekt GoogleAdsFailure jest zwracany jako część metadanych końcowych w nagłówkach odpowiedzi gRPC. Jeśli do standardowych połączeń używasz interfejsu REST, w odpowiedzi HTTP zwracana jest wartość GoogleAdsFailure. Biblioteki klienta zwykle zgłaszają to jako wyjątek z atrybutem GoogleAdsFailure.

Częściowe niepowodzenie

Jeśli używasz częściowego niepowodzenia, błędy dotyczące nieudanych operacji są zwracane w polu partial_failure_error odpowiedzi, a nie w nagłówkach odpowiedzi. W takim przypadku obiekt GoogleAdsFailure jest osadzony w obiekcie google.rpc.Status w odpowiedzi.

Zadania wsadowe

W przypadku przetwarzania wsadowego błędy poszczególnych operacji można znaleźć, pobierając wyniki zadania wsadowego po jego zakończeniu. Każdy wynik operacji będzie zawierać pole status z informacjami o błędzie, jeśli operacja się nie powiodła.

Identyfikator żądania

request-id to unikalny ciąg znaków, który identyfikuje Twoje żądanie interfejsu API i jest niezbędny do rozwiązywania problemów.

request-id znajdziesz w kilku miejscach:

  • GoogleAdsFailure: jeśli wywołanie interfejsu API nie powiedzie się i zostanie zwrócony kod GoogleAdsFailure, będzie on zawierać kod request_id.
  • Metadane końcowe: w przypadku żądań zakończonych powodzeniem i niepowodzeniem w metadanych końcowych odpowiedzi gRPC dostępny jest parametr request-id.
  • Nagłówki odpowiedzi: w przypadku udanych i nieudanych żądań wartość request-id jest też dostępna w nagłówkach odpowiedzi gRPC i HTTP, z wyjątkiem udanych żądań przesyłania strumieniowego.
  • SearchGoogleAdsStreamResponse: w przypadku żądań przesyłania strumieniowego każda SearchGoogleAdsStreamResponse wiadomość zawiera pole request_id.

Podczas rejestrowania błędów lub kontaktowania się z zespołem pomocy pamiętaj, aby podać request-id, co ułatwi diagnozowanie problemów.

Sprawdzone metody obsługi błędów

Aby tworzyć odporne aplikacje, stosuj te sprawdzone metody:

  1. Sprawdź szczegóły błędu: zawsze analizuj pole details obiektu Status, zwracając szczególną uwagę na GoogleAdsFailure. Szczegółowe informacje errorCode, message i location w ramach GoogleAdsError dostarczają najbardziej przydatnych informacji do debugowania i opinii użytkowników.

  2. Odróżniaj błędy klienta od błędów serwera:

    • Błędy klienta: kody takie jak INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Wymagają one zmian w żądaniu lub w stanie/danych logowania aplikacji. Nie ponawiaj żądania bez rozwiązania problemu.
    • Błędy serwera: kody takie jak UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Wskazują one na tymczasowy problem z usługą API.

  3. Wdróż strategię ponawiania:

    • Kiedy ponawiać próbę: ponawiaj próbę tylko w przypadku przejściowych błędów serwera, takich jak UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN i ABORTED.
    • Wzrastający czas do ponowienia: użyj algorytmu wzrastającego czasu do ponowienia, aby czekać coraz dłużej między ponownymi próbami. Pomaga to uniknąć przeciążenia już i tak obciążonej usługi. Na przykład odczekaj 1 sekundę, potem 2 sekundy, a następnie 4 sekundy, aż do osiągnięcia maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania.
    • Jitter: dodaj niewielką losową wartość „jitter” do opóźnień wycofywania, aby zapobiec problemowi „thundering herd”, w którym wielu klientów ponawia próbę jednocześnie.

  4. Dokładnie rejestruj błędy: rejestruj pełną odpowiedź o błędzie, w tym wszystkie szczegóły, a zwłaszcza identyfikator żądania. Te informacje są niezbędne do debugowania i zgłaszania problemów zespołowi pomocy Google.

  5. Przekazywanie opinii użytkowników: na podstawie konkretnych kodów i wiadomości GoogleAdsError przekazuj użytkownikom aplikacji jasne i przydatne informacje zwrotne. Na przykład zamiast „Wystąpił błąd” możesz podać „Wymagana jest nazwa kampanii” lub „Nie znaleziono podanego identyfikatora grupy reklam”.

Przestrzegając tych wytycznych, możesz skutecznie diagnozować i obsługiwać błędy zwracane przez interfejs Google Ads API, co pozwoli Ci tworzyć bardziej stabilne i przyjazne dla użytkownika aplikacje.