Informacje o błędach interfejsu API

Z tego przewodnika dowiesz się, jak interfejs Google Ads API obsługuje i komunikuje błędy. Zrozumienie struktury i znaczenia błędów interfejsu API jest kluczowe dla tworzenia solidnych aplikacji, które mogą bezproblemowo 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 interfejsu 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 obejmuje:

  • Numeryczny kod błędu.
  • komunikat o błędzie,
  • Opcjonalne, dodatkowe szczegóły błędu.

Kanoniczne kody błędów

Interfejs Google Ads API używa zestawu kanonicznych kodów błędów zdefiniowanych przez gRPC i HTTP. Te kody wskazują ogólny typ błędu. Zawsze najpierw sprawdzaj ten kod numeryczny, aby poznać podstawową przyczynę problemu.

W tabeli poniżej znajdziesz najczęstsze kody, 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 informacji znajdziesz w komunikacie o błędzie lub w szczegółach. Traktuj jako błąd serwera. Często można ponowić próbę z wycofaniem.
3 400 INVALID_ARGUMENT Klient podał nieprawidłowy argument. Wskazuje to na 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ą wymagania interfejsu API. Szczegóły błędu zwykle zawierają informacje o tym, który argument był nieprawidłowy i w jaki sposób. Użyj tych informacji, aby poprawić żądanie. Nie ponawiaj próby bez poprawienia żądania.
4 504 DEADLINE_EXCEEDED Termin upłynął, zanim operacja została ukończona. Błąd serwera: często przejściowy. Rozważ ponowienie próby ze wzrastającym czasem 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 wprowadzenia poprawek.
6 409 ALREADY_EXISTS Encja, którą klient próbował utworzyć, już istnieje. Błąd klienta: unikaj tworzenia zduplikowanych zasobów. Przed próbą utworzenia zasobu sprawdź, czy on istnieje.
7 403 PERMISSION_DENIED 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, dopóki nie rozwiążesz 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 poczekania. Zaimplementuj wzrastający czas do ponowienia i ewentualnie zmniejsz częstotliwość wniosków. Zobacz Limity i limity dla interfejsu API.
9 400 FAILED_PRECONDITION Operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania. Może to być na przykład brak wymaganego pola. Błąd klienta: żądanie jest prawidłowe, ale stan jest nieprawidłowy. Sprawdź szczegóły błędu, aby dowiedzieć się, dlaczego warunek wstępny nie został spełniony. 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 bezpiecznie ponowić próbę po krótkim czasie oczekiwania.
11 400 OUT_OF_RANGE Próba wykonania operacji 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 ponawiaj próby.
13 500 INTERNAL Wystąpił błąd wewnętrzny. Jest to ogólny błąd dotyczący problemów po stronie serwera. Błąd serwera: zwykle można spróbować ponownie, stosując wzrastający czas do ponowienia. Jeśli problem będzie się powtarzał, zgłoś go.
14 503 UNAVAILABLE Usługa jest czasowo niedostępna. Jest to najprawdopodobniej stan przejściowy. Błąd serwera: zdecydowanie zalecamy ponowienie próby ze wzrastającym czasem do ponowienia.
15 500 DATA_LOSS Nieodwracalna utrata lub uszkodzenie danych. Błąd serwera: rzadko. Wskazuje poważny problem. Nie ponawiaj próby. 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 uwierzytelniania 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 proto GoogleAdsFailure, które obejmuje 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.
  • request_id: unikalny identyfikator żądania, przydatny do debugowania i rozwiązywania problemów.

Każdy obiekt GoogleAdsError zawiera:

Przykładowe szczegóły błędu

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

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

W tym przykładzie, pomimo błędu najwyższego poziomu INVALID_ARGUMENT, szczegóły GoogleAdsFailure informują, że problem spowodowały pola name i description, oraz podają przyczynę (odpowiednio REQUIRED i TOO_SHORT).

Znajdowanie szczegółów 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 strumieniowania.

Standardowe i strumieniowe wywołania interfejsu API

Gdy wywołanie interfejsu API nie powiedzie się bez użycia częściowego niepowodzenia, w tym wywołania strumieniowe, obiekt GoogleAdsFailure jest zwracany jako część metadanych końcowych w nagłówkach odpowiedzi gRPC. Jeśli używasz REST do standardowych wywołań, w odpowiedzi HTTP zwracany jest parametr GoogleAdsFailure. Biblioteki klienta zwykle wyświetlają to jako wyjątek z atrybutem GoogleAdsFailure.

Częściowe niepowodzenie

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

Zadania wsadowe

W przypadku przetwarzania wsadowego błędy poszczególnych operacji można znaleźć, wywołując BatchJobService.ListBatchJobResults po zakończeniu zadania. Każdy wynik operacji będzie zawierać pole status ze szczegółami błędu, jeśli operacja się nie powiedzie.

Identyfikator żądania

request-id to unikalny ciąg znaków, który identyfikuje żądanie do 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 błąd GoogleAdsFailure, będzie on zawierać request_id.
  • Metadane końcowe: zarówno w przypadku żądań zakończonych powodzeniem, jak i niepowodzeniem, request-id jest dostępny w metadanych końcowych odpowiedzi gRPC.
  • Nagłówki odpowiedzi: w przypadku żądań zakończonych powodzeniem i niepowodzeniem parametr request-id jest też dostępny w nagłówkach odpowiedzi gRPC i odpowiedzi HTTP, z wyjątkiem żądań strumieniowych zakończonych powodzeniem.
  • SearchGoogleAdsStreamResponse: w przypadku żądań strumieniowych każda wiadomość SearchGoogleAdsStreamResponse zawiera pole request_id.

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

Sprawdzone metody obsługi błędów

Aby tworzyć odporne aplikacje, stosuj te sprawdzone metody:

  1. Sprawdzaj szczegóły błędu: zawsze analizuj pole details obiektu Status, zwracając szczególną uwagę na GoogleAdsFailure. Szczegółowe informacje o error_code, message i location w GoogleAdsError zapewniają najbardziej przydatne informacje do debugowania i opinii użytkowników.

  2. Rozróżnianie błędów klienta i 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 stanie/danych logowania aplikacji. Nie ponawiaj żądania bez rozwiązania problemu.
    • Błędy serwera: kody takie jak UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Sugerują one tymczasowy problem z usługą interfejsu API.

  3. Wdrażanie strategii ponawiania prób:

    • Kiedy ponowić próbę: ponów 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 wydłużać czas oczekiwania między kolejnymi próbami. Pomaga to uniknąć przeciążenia już i tak obciążonej usługi. Na przykład poczekaj 1 sekundę, potem 2 sekundy, potem 4 sekundy, aż do osiągnięcia maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania.
    • Wahania: dodaj niewielką losową wartość „wahań” do opóźnień wycofywania, aby zapobiec problemowi „grzmiącego stada”, gdy wielu klientów ponawia próbę jednocześnie.

  4. Zapisuj szczegółowe dzienniki: zapisuj 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żytkownikom: na podstawie konkretnych kodów i komunikatów GoogleAdsError przekazuj użytkownikom aplikacji jasne i pomocne informacje. Na przykład zamiast „Wystąpił błąd” możesz powiedzieć „Nazwa kampanii jest wymagana” lub „Nie znaleziono podanego identyfikatora grupy reklam”.

Dzięki przestrzeganiu tych wskazówek 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.

Wstecz
Typy błędów
Dalej
Typowe błędy