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

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

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

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

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

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

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

Более подробную информацию об этих кодах можно найти в Руководстве по проектированию 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 , чтобы облегчить диагностику проблем.

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

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

1. Проверьте сведения об ошибке: всегда анализируйте поле details объекта Status , обращая особое внимание на GoogleAdsFailure . Подробные errorCode , message и location в GoogleAdsError предоставляют наиболее полезную информацию для отладки и обратной связи с пользователем.

2. Различайте ошибки клиента и сервера:

   • Ошибки клиента: коды типа INVALID_ARGUMENT , NOT_FOUND , PERMISSION_DENIED , FAILED_PRECONDITION , UNAUTHENTICATED . Они требуют изменения запроса или состояния/учётных данных вашего приложения. Не повторяйте запрос, не устранив проблему.
   • Ошибки сервера: коды типа UNAVAILABLE , INTERNAL , DEADLINE_EXCEEDED , UNKNOWN . Они указывают на временную проблему со службой API.

3. Реализуйте стратегию повторных попыток:

   • Когда повторять попытку: Повторяйте попытку только в случае временных ошибок сервера, таких как UNAVAILABLE , DEADLINE_EXCEEDED , INTERNAL , UNKNOWN и ABORTED .
   • Экспоненциальная задержка: используйте алгоритм экспоненциальной задержки для увеличения интервалов ожидания между повторными попытками. Это помогает избежать перегрузки и без того нагруженного сервиса. Например, подождите 1 секунду, затем 2 секунды, затем 4 секунды, продолжая до достижения максимального количества повторных попыток или общего времени ожидания.
   • Джиттер: добавьте небольшое случайное количество «джитер» к задержкам отсрочки, чтобы предотвратить проблему «громового стада», когда множество клиентов одновременно повторяют попытки.

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

5. Предоставляйте обратную связь: предоставляйте пользователям вашего приложения понятную и полезную обратную связь на основе конкретных кодов и сообщений GoogleAdsError . Например, вместо просто «Произошла ошибка» можно указать «Требуется название кампании» или «Указанный идентификатор группы объявлений не найден».

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