Чтобы обсудить наши продукты и оставить отзыв, присоединяйтесь к официальному каналу Google Ads в Discord на сервере Google Advertising and Measurement Community .

Эта страница переведена с помощью Cloud Translation API.

Понимание ошибок API

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

API Google Ads следует стандартной модели ошибок API Google, основанной на кодах статуса gRPC . Каждый ответ API, приводящий к ошибке, включает объект Status содержащий:

Числовой код ошибки.
Сообщение об ошибке.
Необязательные дополнительные сведения об ошибке.

Канонические коды ошибок

API Google Ads использует набор канонических кодов ошибок, определяемых gRPC и HTTP. Эти коды предоставляют общую информацию о типе ошибки. Всегда следует сначала проверять этот числовой код, чтобы понять суть проблемы.

В следующей таблице приведены наиболее распространенные коды, с которыми вы можете столкнуться при использовании API Google Ads:

код gRPC	HTTP-код	Имя перечисления	Описание	Руководство
0	200	`OK`	Ошибок нет; указывает на успех.	Н/Д
1	499	`CANCELLED`	Операция была отменена, как правило, клиентом.	Обычно это означает, что клиент перестал ждать. Проверьте тайм-ауты на стороне клиента.
2	500	`UNKNOWN`	Произошла неизвестная ошибка. Более подробная информация может быть в сообщении об ошибке или в описании.	Рассматривать как ошибку сервера. Часто можно повторить попытку с отсрочкой.
3	400	`INVALID_ARGUMENT`	Клиент указал недопустимый аргумент. Это указывает на проблему, препятствующую обработке запроса API, например, на неверно сформированное имя ресурса или недопустимое значение.	Ошибка клиента: проверьте параметры запроса и убедитесь, что они соответствуют требованиям API. Информация об ошибке обычно содержит информацию о том, какой аргумент был недействителен и как именно — используйте эту информацию для исправления запроса. Не повторяйте попытку, пока не исправите запрос.
4	504	`DEADLINE_EXCEEDED`	Срок истек до того, как операция была завершена.	Ошибка сервера: часто временная. Рассмотрите возможность повторной попытки с экспоненциальной задержкой .
5	404	`NOT_FOUND`	Некоторые запрошенные объекты, например кампания или группа объявлений, не найдены.	Ошибка клиента: проверьте наличие и идентификатор ресурсов, к которым вы пытаетесь получить доступ. Не повторяйте попытку без исправления.
6	409	`ALREADY_EXISTS`	Сущность, которую клиент пытался создать, уже существует.	Ошибка клиента: Избегайте создания дублирующихся ресурсов. Перед созданием ресурса проверьте его существование.
7	403	`PERMISSION_DENIED`	У вызывающего абонента нет разрешения на выполнение указанной операции.	Ошибка клиента: проверьте аутентификацию , авторизацию и роли пользователей для аккаунта Google Ads. Не повторяйте попытку без разрешения прав доступа.
8	429	`RESOURCE_EXHAUSTED`	Либо ресурс исчерпан (например, вы превысили квоту), либо система перегружена.	Ошибка клиент/сервер: обычно требует ожидания. Реализуйте экспоненциальную задержку и, возможно, уменьшите частоту запросов. См. раздел «Ограничения и квоты API» .
9	400	`FAILED_PRECONDITION`	Операция отклонена, поскольку система не находится в состоянии, необходимом для её выполнения. Например, отсутствует обязательное поле.	Ошибка клиента: запрос действителен, но состояние неверно. Ознакомьтесь с описанием ошибки, чтобы понять причину сбоя. Не повторяйте попытку без исправления состояния.
10	409	`ABORTED`	Операция была прервана, как правило, из-за проблемы параллелизма, например конфликта транзакций.	Ошибка сервера: зачастую можно безопасно повторить попытку с небольшой задержкой.
11	400	`OUT_OF_RANGE`	Была предпринята попытка выполнить операцию за пределами допустимого диапазона.	Ошибка клиента: Исправьте диапазон или индекс.
12	501	`UNIMPLEMENTED`	Операция не реализована или не поддерживается API.	Ошибка клиента: проверьте версию API и доступные функции. Не повторяйте попытку.
13	500	`INTERNAL`	Произошла внутренняя ошибка. Это общее описание проблем на стороне сервера.	Ошибка сервера: обычно возможна повторная попытка с экспоненциальной задержкой . Если проблема повторяется, сообщите о ней .
14	503	`UNAVAILABLE`	В настоящее время сервис недоступен. Скорее всего, это временная проблема.	Ошибка сервера: настоятельно рекомендуется повторить попытку с экспоненциальной задержкой .
15	500	`DATA_LOSS`	Невосстановимая потеря или повреждение данных.	Ошибка сервера: редкое явление. Указывает на серьёзную проблему. Не повторяйте попытку. Если проблема повторяется, сообщите о ней .
16	401	`UNAUTHENTICATED`	Запрос не имеет действительных учетных данных аутентификации.	Ошибка клиента: Проверьте токены аутентификации и учётные данные. Не повторяйте попытку, пока не исправите ошибки аутентификации.

Более подробную информацию об этих кодах можно найти в Руководстве по проектированию API - Коды ошибок .

Понять детали ошибки

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

Каждый объект GoogleAdsFailure содержит:

errors : список объектов GoogleAdsError , каждый из которых описывает конкретную произошедшую ошибку.
request_id : уникальный идентификатор запроса, полезный для отладки и поддержки.

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

errorCode : более подробный код ошибки, специфичный для API Google Ads , например AuthenticationError.NOT_ADS_USER .
message : понятное для человека описание конкретной ошибки.
trigger : значение, вызвавшее ошибку, если применимо.
location : Описывает, где в запросе произошла ошибка, включая пути к полям.
details : Дополнительные сведения об ошибке, например, неопубликованные причины ошибки.

Пример сведений об ошибке

При возникновении ошибки ваша клиентская библиотека предоставит вам доступ к этим данным. Например, INVALID_ARGUMENT (код 3) может содержать следующие данные GoogleAdsFailure :

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

В этом примере, несмотря на INVALID_ARGUMENT верхнего уровня, сведения GoogleAdsFailure сообщают, что поля name и description вызвали проблему, а также причину ( REQUIRED и TOO_SHORT соответственно).

Найдите сведения об ошибке

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

Стандартные и потоковые вызовы API

При сбое API-вызова без использования частичного отказа, включая потоковые вызовы , объект GoogleAdsFailure возвращается в составе конечных метаданных в заголовках ответа gRPC. При использовании REST для стандартных вызовов GoogleAdsFailure возвращается в HTTP-ответе. Клиентские библиотеки обычно отображают это как исключение с атрибутом GoogleAdsFailure .

Частичный отказ

При использовании частичного отказа ошибки невыполненных операций возвращаются в поле partial_failure_error ответа, а не в заголовках ответа. В этом случае GoogleAdsFailure встроен в объект google.rpc.Status в ответе.

Пакетные задания

При пакетной обработке ошибки отдельных операций можно обнаружить, извлекая результаты пакетного задания после его завершения. Результат каждой операции будет включать поле status с подробностями об ошибке, если операция завершилась неудачно.

Запрос идентификатора

request-id — это уникальная строка, которая идентифицирует ваш запрос API и необходима для устранения неполадок.

request-id можно найти в нескольких местах:

GoogleAdsFailure : если вызов API завершается неудачей и возвращается GoogleAdsFailure , он будет содержать request_id .
Конечные метаданные : как для успешных, так и для неудачных запросов request-id доступен в конечных метаданных ответа gRPC.
Заголовки ответов : как для успешных, так и для неудачных запросов request-id также доступен в заголовках ответов gRPC и HTTP, за исключением успешных потоковых запросов.
SearchGoogleAdsStreamResponse : для потоковых запросов каждое сообщение SearchGoogleAdsStreamResponse содержит поле request_id .

При регистрации ошибок или обращении в службу поддержки обязательно указывайте request-id , чтобы облегчить диагностику проблем.

Лучшие практики обработки ошибок

Для создания отказоустойчивых приложений реализуйте следующие рекомендации:

Проверьте сведения об ошибке: всегда анализируйте поле details объекта Status , обращая особое внимание на GoogleAdsFailure . Подробные errorCode , message и location в GoogleAdsError предоставляют наиболее полезную информацию для отладки и обратной связи с пользователем.
Различайте ошибки клиента и сервера:
- Ошибки клиента: коды типа INVALID_ARGUMENT , NOT_FOUND , PERMISSION_DENIED , FAILED_PRECONDITION , UNAUTHENTICATED . Они требуют изменения запроса или состояния/учётных данных вашего приложения. Не повторяйте запрос, не устранив проблему.
- Ошибки сервера: коды типа UNAVAILABLE , INTERNAL , DEADLINE_EXCEEDED , UNKNOWN . Они указывают на временную проблему со службой API.
Реализуйте стратегию повторных попыток:
- Когда повторять попытку: Повторяйте попытку только в случае временных ошибок сервера, таких как UNAVAILABLE , DEADLINE_EXCEEDED , INTERNAL , UNKNOWN и ABORTED .
- Экспоненциальная задержка: используйте алгоритм экспоненциальной задержки для увеличения интервалов ожидания между повторными попытками. Это помогает избежать перегрузки и без того нагруженного сервиса. Например, подождите 1 секунду, затем 2 секунды, затем 4 секунды, продолжая до достижения максимального количества повторных попыток или общего времени ожидания.
- Джиттер: добавьте небольшое случайное количество «джитер» к задержкам отсрочки, чтобы предотвратить проблему «громового стада», когда множество клиентов одновременно повторяют попытки.
Тщательное протоколирование: регистрируйте полный ответ об ошибке, включая все детали, особенно идентификатор запроса. Эта информация важна для отладки и для сообщения о проблемах в службу поддержки Google при необходимости.
Предоставляйте обратную связь: предоставляйте пользователям вашего приложения понятную и полезную обратную связь на основе конкретных кодов и сообщений GoogleAdsError . Например, вместо просто «Произошла ошибка» можно указать «Требуется название кампании» или «Указанный идентификатор группы объявлений не найден».

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

Типы ошибок

Распространенные ошибки

Понимание ошибок API Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.