Обработка ошибок API

При отправке запроса к API Google Ads он может завершиться неудачей по разным причинам. Например, вы можете указать недопустимый аргумент или ваш аккаунт может достичь лимита на создание новых кампаний. В таких случаях API возвращает ошибку, чтобы сообщить вам, что пошло не так.

В этом руководстве объясняется, как читать и обрабатывать ошибки API, чтобы вы могли создавать более надежные приложения.

Структура ошибок

Если вы используете одну из наших клиентских библиотек , ошибки API отображаются в виде исключений. Эти исключения содержат подробную информацию, которая поможет вам понять, почему произошла ошибка.

API Google Ads возвращает информацию об ошибках в стандартном формате. В случае ошибки ответ будет содержать объект GoogleAdsFailure . Этот объект содержит список отдельных объектов GoogleAdsError , каждый из которых описывает конкретную ошибку.

Каждый объект GoogleAdsError предоставляет:

• error_code : Конкретный код ошибки, указывающий на тип ошибки, например, AuthenticationError.NOT_ADS_USER .
• message : удобочитаемое описание причины возникновения ошибки.
• trigger : Значение, вызвавшее ошибку, например, "1234".
• location : Подробная информация о том, какая часть запроса вызвала ошибку, например, название конкретного поля.

Помимо списка ошибок, GoogleAdsFailure содержит requestId , уникальный идентификатор запроса API, который привел к ошибке.

Пример ошибки

Вот пример того, как выглядит ошибка в формате JSON. Эта ошибка указывает на то, что в запросе отсутствует поле name объекта ad_group с индексом 0 .

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v23.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"
    }
  ]
}

Для получения более подробной информации об ошибках API обратитесь к нашему руководству .

Примеры клиентских библиотек

В следующем разделе показано, как обрабатывать ошибки в различных клиентских библиотеках.

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an API request.
  // Instances of this exception have a message and a GoogleAdsFailure that contains a
  // collection of GoogleAdsErrors that indicate the underlying causes of the
  // GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

try {
  // Make an API call.
  ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(f"\tError with message '{error.message}' and code '{error.error_code}'.")

begin
    # Make an API call.
    ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
    puts "API call failed with request ID: #{e.request_id}"
    e.failure.errors.each do |error|
        puts "\t#{error.error_code}: #{error.message}"
    end
end

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n", [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

Как собирать журналы событий

Для устранения ошибок перехватите журналы ошибок, возвращаемые сервером Google Ads API, и изучите их содержимое. Следуйте приведенным ниже инструкциям, чтобы включить ведение журналов и перехват журналов API.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Как обрабатывать ошибки

Если вы столкнулись с ошибкой, выполните следующие действия:

1. Перехват исключений и сбор логов : начните с перехвата исключений и, при необходимости, сбора логов API.
2. Изучите список errors : просмотрите каждую GoogleAdsError в объекте GoogleAdsFailure . error_code и message укажут на причину проблемы.
3. Проверьте значение поля location location : это поле поможет вам точно определить, в какой части вашего запроса возникла проблема.
4. Обратитесь к документации : для получения информации о конкретных кодах ошибок ознакомьтесь со страницей распространенных ошибок или полным справочником кодов ошибок, чтобы узнать подробности об ошибке и способах ее устранения.
5. Скорректируйте свой запрос : исходя из сообщения об ошибке, исправьте свой API-запрос. Например, если вы видите REQUIRED_FIELD_MISSING , убедитесь, что вы указали это поле в своем запросе.
6. Укажите request_id в логе : если вы не можете понять, как устранить ошибку, и вам нужно обратиться в службу поддержки , приложите полные логи запроса и ответа для неудачного запроса. Обязательно укажите request_id . Этот идентификатор поможет инженерам Google найти подробную информацию о неудачном запросе в логах сервера Google Ads API и разобраться с вашей проблемой.

Следующие шаги

• В разделе «Распространенные ошибки» представлен список часто встречающихся проблем и способов их решения.
• Для получения более подробной информации о методах обработки ошибок, включая логику повторных попыток и частичные сбои, см. раздел «Понимание ошибок API» .