Obsługa błędów interfejsu API

Gdy wysyłasz żądanie do interfejsu Google Ads API, może ono zostać niezrealizowane z różnych powodów. Możesz na przykład podać nieprawidłowy argument lub Twoje konto mogło osiągnąć limit tworzenia nowych kampanii. W takich przypadkach interfejs API zwraca błąd, aby poinformować Cię, co poszło nie tak.

Z tego przewodnika dowiesz się, jak odczytywać błędy interfejsu API i sobie z nimi radzić, aby tworzyć bardziej niezawodne aplikacje.

Struktura błędu

Jeśli używasz jednej z naszych bibliotek klienta, błędy interfejsu API są zgłaszane jako wyjątki. Te wyjątki zawierają szczegóły, które pomogą Ci zrozumieć, dlaczego wystąpił błąd.

Interfejs Google Ads API zwraca informacje o błędach w standardowym formacie. Jeśli wystąpi błąd, odpowiedź będzie zawierać obiekt GoogleAdsFailure. Ten obiekt zawiera listę poszczególnych obiektów GoogleAdsError, z których każdy zawiera szczegółowe informacje o określonym błędzie.

Każdy obiekt GoogleAdsError zawiera:

• error_code: konkretny kod błędu, który informuje o jego rodzaju, np. AuthenticationError.NOT_ADS_USER.
• message: czytelny dla człowieka opis przyczyny wystąpienia błędu.
• trigger: wartość, która spowodowała błąd, np. „1234”.
• location: szczegóły dotyczące części żądania, która spowodowała błąd, np. nazwa konkretnego pola.

Oprócz listy błędów element GoogleAdsFailure zawiera element requestId, który jest unikalnym identyfikatorem żądania do interfejsu API, które spowodowało błąd.

Przykładowy błąd

Oto przykład błędu w formacie JSON. Ten błąd oznacza, że w żądaniu brakuje pola name elementu ad_group o indeksie 0.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Jak radzić sobie z błędami

Jeśli pojawi się błąd, wykonaj te czynności:

1. Sprawdź listę errors: przyjrzyj się każdemu elementowi GoogleAdsError w obiekcie GoogleAdsFailure. Ikony error_code i message poinformują Cię, co poszło nie tak.
2. Sprawdź pole location: pole location może pomóc w określeniu, w którym miejscu żądania wystąpił problem.
3. Zapoznaj się z dokumentacją: w przypadku konkretnych kodów błędów sprawdź stronę z typowymi błędami lub pełną listę kodów błędów, aby uzyskać więcej informacji o błędzie i sposobie jego naprawienia.
4. Dostosuj żądanie: na podstawie komunikatu o błędzie popraw żądanie do interfejsu API. Jeśli na przykład widzisz REQUIRED_FIELD_MISSING, upewnij się, że to pole jest uwzględnione w żądaniu.
5. Zapisz request_id: jeśli nie możesz znaleźć rozwiązania błędu i musisz skontaktować się z zespołem pomocy na forum, podaj request_id. Ten identyfikator pomoże inżynierom Google zbadać Twój problem.

Dalsze kroki

• Listę częstych problemów i sposobów ich rozwiązywania znajdziesz w sekcji Typowe błędy.
• Bardziej zaawansowane techniki obsługi błędów, w tym logikę ponawiania i częściowe niepowodzenie, znajdziesz w artykule Wyjaśnienie błędów interfejsu API.