Обработка ошибок 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.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"
    }
  ]
}

Более подробную информацию об ошибках 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};
  }
}

Как вести журналы

Для устранения ошибок сохраните журналы ошибок, возвращаемые сервером API Google Ads, и проверьте их содержимое. Чтобы включить ведение журнала и сохранить журналы 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 найти информацию о невыполненном запросе в журналах сервера API Google Ads и изучить вашу проблему.

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

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