Запрос к Google Ads API может не выполниться по разным причинам. Например, вы могли указать недопустимый аргумент или в вашем аккаунте достигнуто ограничение на создание новых кампаний. В таких случаях API возвращает ошибку, чтобы вы знали, что пошло не так.
В этом руководстве рассказывается, как читать и обрабатывать ошибки API, чтобы создавать более надежные приложения.
Структура ошибки
Если вы используете одну из наших клиентских библиотек, ошибки API будут отображаться как исключения. В них содержатся сведения, которые помогут вам понять, почему произошла ошибка.
Google Ads API возвращает информацию об ошибках в стандартном формате. Если произойдет ошибка, ответ будет содержать объект 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.v26.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…
Примеры клиентских библиотек
В следующем разделе показано, как обрабатывать ошибки в различных клиентских библиотеках.
Java
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);
}
}
C#
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}");
}
}
PHP
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
);
$errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
foreach ($errors as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
}
Python
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 "
f"'{error.error_code}'."
)
Ruby
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
Perl
# 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, следуйте инструкциям ниже.
Java
Инструкции вы найдете в руководстве по ведению журналов в клиентской библиотеке Java.
C#
Чтобы инициализировать ведение журнала, добавьте следующую строку в метод Main перед вызовами 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);
Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке .NET.
PHP
Вы можете задать конфигурацию ведения журнала в файле google_ads_php.ini клиентской библиотеки. Чтобы начать сбор подробных журналов ошибок, задайте для параметра logLevel значение NOTICE.
[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"
Инструкции вы найдете в руководстве по ведению журнала в клиентской библиотеке PHP.
Python
Вы можете задать конфигурацию ведения журнала в файле google-ads.yaml клиентской библиотеки. Установите уровень ведения журнала DEBUG, чтобы начать сбор подробных журналов ошибок.
Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Python.
Ruby
Вы можете задать конфигурацию ведения журнала в файле google_ads_config.rb клиентской библиотеки. Установите уровень ведения журнала INFO, чтобы начать сбор подробных журналов ошибок.
Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Ruby.
Perl
Чтобы инициализировать ведение журнала, добавьте в скрипт Perl следующую строку перед вызовами API:
Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();
Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Perl.
curl
По умолчанию curl выводит ответы с ошибками в stderr.
Как устранять ошибки
Если вы столкнулись с ошибкой, выполните следующие действия:
- Перехватите исключение и запишите журналы. Сначала перехватите исключения и при необходимости запишите журналы API.
- Изучите список
errors. Посмотрите на каждый элементGoogleAdsErrorв объектеGoogleAdsFailure.error_codeиmessageсообщат вам, что пошло не так. - Проверьте значение
location. Полеlocationпоможет вам определить, в какой части запроса возникла проблема. - Изучите документацию. Если вы столкнулись с определенными кодами ошибок, ознакомьтесь со статьей Распространенные ошибки или полным списком кодов ошибок, чтобы узнать больше об ошибке и способах ее устранения.
- Скорректируйте запрос. Исправьте запрос к API на основе сообщения об ошибке. Например, если вы видите
REQUIRED_FIELD_MISSING, убедитесь, что вы указали это поле в запросе. - Зарегистрируйте
request_id. Если вы не можете устранить ошибку и вам нужно обратиться в службу поддержки, включите в обращение полные журналы запросов и ответов для запроса, который не удалось выполнить. Обязательно укажитеrequest_id. Этот идентификатор помогает инженерам Google найти сведения о неудачном запросе в журналах сервера Google Ads API и изучить проблему.
Дальнейшие действия
- Ознакомьтесь с распространенными ошибками и способами их устранения.
- Дополнительные сведения об обработке ошибок, в том числе о логике повторных попыток и частичных сбоях, можно найти в статье Общие сведения об ошибках API.