Обработка ошибок API

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

В этом руководстве объясняется, как распознавать и обрабатывать ошибки API, чтобы вы могли создавать более надежные приложения.

Структура ошибки

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

API Google Ads возвращает информацию об ошибках в стандартном формате. В случае возникновения ошибки ответ будет содержать объект 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.v22.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"
    }
  ]
}

Как обрабатывать ошибки

Если вы столкнулись с ошибкой, вот шаги, которые следует предпринять:

1. Изучите список errors : просмотрите каждую GoogleAdsError в объекте GoogleAdsFailure . error_code и message подскажут вам, что произошло.
2. Проверьте location : поле location может помочь вам точно определить, где в вашем запросе возникла проблема.
3. Обратитесь к документации : для получения более подробной информации об ошибке и способах ее устранения проверьте страницу с описанием распространенных ошибок или полный справочник кодов ошибок .
4. Скорректируйте запрос : в зависимости от сообщения об ошибке исправьте свой API-запрос. Например, если вы видите REQUIRED_FIELD_MISSING , убедитесь, что вы указали это поле в запросе.
5. Зарегистрируйте request_id : если вы не можете понять, как устранить ошибку, и вам нужно обратиться в службу поддержки через форум , укажите request_id . Этот идентификатор поможет инженерам Google разобраться в вашей проблеме.

Следующие шаги

• Просмотрите раздел «Распространенные ошибки» , где представлен список часто встречающихся проблем и их решений.
• Более продвинутые методы обработки ошибок, включая логику повторных попыток и частичный сбой, см. в разделе Понимание ошибок API .