Типы ошибок

Мы разделили ошибки на следующие основные категории:

  • Аутентификация
  • Ошибки, которые можно исправить повторно.
  • Валидация
  • Синхронизация

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

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

Ошибки аутентификации

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

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

Аналогично, если ваш проект Google Cloud имеет только тестовый уровень доступа и пытается отправлять запросы к производственной (не тестовой) учетной записи, API возвращает ошибку AuthorizationError значение перечисления которой зависит от версии API:

Ошибки, которые можно исправить повторно.

Некоторые ошибки, такие как TRANSIENT_ERROR или INTERNAL_ERROR , могут указывать на временную проблему, которую можно устранить, повторив запрос после небольшой паузы.

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

Для запросов, инициированных на стороне бэкэнда, ваше приложение должно автоматически повторять запрос, но не более определенного количества раз.

При повторных запросах используйте политику экспоненциальной задержки с рандомизированным дрожанием. Например, если вы сначала делаете паузу в 5 секунд перед первым повторным запросом, вы можете сделать паузу в 10 секунд после второго и 20 секунд после третьего повторного запроса, добавив небольшую случайную задержку к каждому интервалу, чтобы предотвратить синхронизированные всплески повторных запросов. Экспоненциальная задержка помогает гарантировать, что вы не обращаетесь к API слишком агрессивно. Если ошибка сохраняется после исчерпания всех повторных попыток, запишите request-id из ответа для устранения неполадок.

Ошибки проверки

Ошибки проверки указывают на то, что входные данные для операции были неприемлемы. Примеры включают PolicyViolationError , DateError , DateRangeError , StringLengthError и UrlFieldError .

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

Многие приложения Google Ads используют локальную базу данных для хранения объектов Google Ads. Одна из проблем такого подхода заключается в том, что локальная база данных может рассинхронизироваться с фактическими объектами в Google Ads. Например, пользователь может удалить группу объявлений непосредственно в Google Ads, но приложение и локальная база данных не знают об этом изменении и продолжают отправлять вызовы API, как если бы группа объявлений существовала. Эти проблемы синхронизации могут проявляться в виде различных ошибок, таких как DUPLICATE_CAMPAIGN_NAME , DUPLICATE_ADGROUP_NAME , AD_NOT_UNDER_ADGROUP , CANNOT_OPERATE_ON_REMOVED_ADGROUPAD и многих других.

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

В случае запросов к бэкэнду, некоторые ошибки предоставляют достаточно информации для автоматического и поэтапного исправления локальной базы данных вашим приложением. Например, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD должна привести к тому, что ваше приложение пометит объявление как удаленное в локальной базе данных. Ошибки, которые вы не можете обработать таким образом, могут привести к запуску более полной задачи синхронизации или к добавлению объявления в очередь для проверки оператором.

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