Эта страница переведена с помощью 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 , чтобы облегчить диагностику проблем.

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