Типы ошибок

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

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

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

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

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

Самая распространенная причина ошибки аутентификации, которая возникает из-за факторов, не зависящих от вас, заключается в том, что аутентифицированный пользователь отозвал разрешение, которое он дал вашему приложению, действовать от его имени. Например, если ваше приложение управляет отдельными аккаунтами Google Рекламы для независимых клиентов и проходит аутентификацию отдельно для каждого клиента при управлении его аккаунтом, клиент может в любой момент отозвать доступ вашего приложения. В зависимости от того, когда был отозван доступ, 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. Если запрос поступил от серверной части, приложение может добавить неудачную операцию в очередь для проверки оператором.

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

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

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

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