Типы ошибок

Мы классифицировали ошибки по следующим основным категориям:

  • Аутентификация
  • Повторяемый
  • Проверка
  • Синхронизация

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

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

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

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

Повторяющиеся ошибки

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

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

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

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

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

Ошибки валидации указывают на то, что входные данные для операции были недопустимыми. Например, 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 должна привести к тому, что ваше приложение пометит это объявление как удалённое в локальной базе данных. Ошибки, которые невозможно обработать таким образом, могут привести к запуску приложением более полной задачи синхронизации или к добавлению в очередь для проверки оператором.

Далее
Распространенные ошибки