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

Как анализировать ошибки API

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

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

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

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

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

В таблице ниже приведены наиболее распространенные коды ошибок, которые могут возникать при использовании Google Ads API.

Код 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 Рекламы. Не повторяйте попытку, пока не решите проблему с разрешениями.
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 — коды ошибок.

Как анализировать сведения об ошибках

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

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

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

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

error_code – более подробная ошибка, связанная с Google Ads APIErrorCode (распространенные ошибки), например AuthenticationError.NOT_ADS_USER.
message – человекочитаемое описание ошибки.
trigger – Value, который вызвал ошибку (если применимо).
location – объект ErrorLocation, описывающий, где в запросе произошла ошибка, включая пути к полям.
details – дополнительные ErrorDetails, например неопубликованные причины ошибок.

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

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

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

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

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

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

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

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

Частичный сбой

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

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

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

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

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

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

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

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

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