API Google Диска возвращает два уровня информации об ошибках:
- Коды ошибок HTTP и заголовочные сообщения.
- Объект JSON в теле ответа с дополнительными сведениями, которые помогут вам определить, как обрабатывать ошибку.
Приложения Google Drive должны перехватывать и обрабатывать все ошибки, которые могут возникнуть при использовании REST API. В этом руководстве содержатся инструкции по устранению конкретных ошибок Drive API.
Сводка кода состояния HTTP
Код ошибки | Описание |
---|---|
200 - OK | Запрос выполнен успешно (это стандартный ответ для успешных HTTP-запросов). |
400 - Bad Request | Запрос не может быть выполнен из-за ошибки клиента в запросе. |
401 - Unauthorized | Запрос содержит недействительные учетные данные. |
403 - Forbidden | Запрос был получен и понят, но у пользователя нет разрешения на выполнение запроса. |
404 - Not Found | Запрошенная страница не найдена. |
429 - Too Many Requests | Слишком много запросов к API. |
500, 502, 503, 504 - Server Errors | При обработке запроса возникла непредвиденная ошибка. |
400 ошибок
Эти ошибки означают, что запрос был неприемлем, часто из-за отсутствия обязательного параметра.
badRequest
Эта ошибка может возникнуть из-за любой из следующих проблем в вашем коде:
- Обязательное поле или параметр не предоставлены.
- Указанное значение или комбинация указанных полей недействительны.
- Вы попытались добавить дубликат родительского файла в файл на Диске.
- Вы попытались добавить родительский элемент, который создал бы цикл в графе каталогов.
Следующий пример JSON представляет собой представление этой ошибки:
{
"error": {
"code": 400,
"errors": [
{
"domain": "global",
"location": "orderBy",
"locationType": "parameter",
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
"reason": "badRequest"
}
],
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
}
}
Чтобы исправить эту ошибку, проверьте поле message
и соответствующим образом скорректируйте свой код.
invalidSharingRequest
Эта ошибка возникает по нескольким причинам. Чтобы определить причину, оцените поле reason
возвращаемого JSON. Эта ошибка чаще всего возникает по следующим причинам:
- Обмен прошел успешно, но уведомление по электронной почте не было доставлено корректно.
- Изменение списка контроля доступа (ACL) не разрешено для этого пользователя.
Поле message
указывает фактическую ошибку.
Поделиться удалось, но уведомление по электронной почте не было доставлено правильно
Следующий пример JSON представляет собой представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "invalidSharingRequest",
"message": "Bad Request. User message: \"Sorry, the items were successfully shared but emails could not be sent to [email protected].\""
}
],
"code": 400,
"message": "Bad Request"
}
}
Чтобы исправить эту ошибку, сообщите пользователю (делящемуся), что он не смог поделиться, поскольку уведомление не может быть отправлено на адрес получателя. Пользователь должен убедиться, что у него правильный адрес электронной почты и что он может получать электронную почту.
Изменение ACL не разрешено для этого пользователя.
Следующий пример JSON представляет собой представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "invalidSharingRequest",
"message": "Bad Request. User message: \"ACL change not allowed.\""
}
],
"code": 400,
"message": "Bad Request"
}
}
Чтобы исправить эту ошибку, проверьте настройки общего доступа домена Google Workspace, к которому принадлежит файл. Настройки могут запрещать общий доступ за пределами домена или общий доступ к общему диску может быть запрещен.
401 ошибка
Эти ошибки означают, что запрос не содержит действительного токена доступа.
authError
Эта ошибка возникает, когда используемый вами токен доступа просрочен или недействителен. Эта ошибка также может быть вызвана отсутствием авторизации для запрошенных областей. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Чтобы исправить эту ошибку, обновите токен доступа с помощью долгосрочного токена обновления. Если это не удается, направьте пользователя через поток OAuth, как описано в разделе Выбор областей API Google Drive .
fileNotDownloadable
Эта ошибка возникает при попытке использовать метод revisions.get
с параметром URL alt=media
в документе Google Workspace. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "fileNotDownloadable",
"message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
}
],
"code": 403,
"message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
- Удалите параметр URL
alt=media
если вы хотите просмотреть метаданные конкретной версии, например MIME-тип. - Используйте метод
files.export
для экспорта байтового содержимого документа Google Workspace. Для получения дополнительной информации см. раздел Экспорт содержимого документа Google Workspace .
403 ошибки
Эти ошибки означают, что превышен лимит использования или у пользователя нет нужных привилегий. Чтобы определить причину, оцените поле reason
возвращенного JSON.
Информацию об ограничениях API Drive см. в разделе Ограничения использования . Информацию об ограничениях папок Drive см. в разделе Ограничения файлов и папок .
activeItemCreationLimitExceeded
Ошибка activeItemCreationLimitExceeded
возникает, когда превышен лимит на количество элементов, созданных для одной учетной записи. Каждый пользователь может создать до 500 миллионов элементов для одной учетной записи. Для получения дополнительной информации см. User-item limit .
{
"error": {
"errors": [
{
"domain": "global",
"reason": "activeItemCreationLimitExceeded",
"message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
}
],
"code": 403,
"message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
}
}
Чтобы исправить эту ошибку:
Сообщите пользователю, что Диск запрещает аккаунтам создавать более 500 миллионов элементов.
Если пользователь должен создавать элементы в этой же учетной записи, попросите его навсегда удалить некоторые объекты. В противном случае он может использовать другую учетную запись, которая уже соответствует требованию.
appNotAuthorizedToFile
Эта ошибка возникает, когда ваше приложение не находится в ACL для файла. Эта ошибка не позволяет пользователю открыть файл с помощью вашего приложения. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "appNotAuthorizedToFile",
"message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
}
],
"code": 403,
"message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
- Откройте окно выбора Google Диска и предложите пользователю открыть файл.
- Попросите пользователя открыть файл с помощью контекстного меню «Открыть с помощью» в пользовательском интерфейсе Диска вашего приложения.
- Используйте метод
files.get
для проверки поляisAppAuthorized
в ресурсеfiles
, чтобы убедиться, что ваше приложение создало или открыло файл.
cannotModifyInheritedTeamDrivePermission
Эта ошибка возникает, когда пользователь пытается изменить унаследованные разрешения элемента на общем диске. Унаследованные разрешения не могут быть удалены из элемента на общем диске. Следующий пример JSON является представлением этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "cannotModifyInheritedTeamDrivePermission",
"message": "Cannot update or delete an inherited permission on a shared drive item."
}
],
"code": 403,
"message": "Cannot update or delete an inherited permission on a shared drive item."
}
}
Чтобы исправить эту ошибку, пользователь должен настроить разрешения на прямой или косвенный родительский элемент, от которого они были унаследованы. Для получения дополнительной информации см. Распространение разрешений . Вы также можете получить ресурс permissions.permissionDetails
, чтобы узнать, унаследованы ли разрешения на этот элемент общего диска или применены напрямую.
dailyLimitExceeded
Эта ошибка возникает, когда достигнут предел API для вашего проекта. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Эта ошибка появляется, когда владелец приложения установил ограничение квоты на использование определенного ресурса. Чтобы исправить эту ошибку, удалите все ограничения на использование для квоты "Запросов в день" .
domainPolicy
Эта ошибка возникает, когда политика домена пользователя не разрешает доступ к Drive через ваше приложение. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Drive apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Drive apps."
}
}
Чтобы исправить эту ошибку:
- Сообщите пользователю, что домен не разрешает вашему приложению доступ к файлам на Диске.
- Попросите пользователя обратиться к администратору домена, чтобы запросить доступ к вашему приложению.
fileOwnerNotMemberOfTeamDrive
Эта ошибка возникает при попытке переместить файл на общий диск, а владелец файла не является его участником. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "fileOwnerNotMemberOfTeamDrive",
"message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
}
],
"code": 403,
"message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
}
}
Чтобы исправить эту ошибку:
Добавьте участника в общий диск с
role=owner
. Для получения дополнительной информации см. Общий доступ к файлам, папкам и дискам .Добавьте файл на общий диск. Для получения дополнительной информации см. Создание и заполнение папок .
fileWriterTeamDriveMoveInDisabled
Эта ошибка возникает, когда администратор домена не разрешил пользователям с role=writer
перемещать элементы на общий диск. Пользователь, пытающийся переместить элементы, имеет меньше разрешений, чем разрешено на целевом общем диске. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "fileWriterTeamDriveMoveInDisabled",
"message": "The domain administrator has not allowed writers to move items into a shared drive."
}
],
"code": 403,
"message": "The domain administrator has not allowed writers to move items into a shared drive."
}
}
Чтобы исправить эту ошибку, используйте одну и ту же учетную запись администратора на исходном и целевом общих дисках.
insufficientFilePermissions
Эта ошибка возникает, когда у пользователя нет прав на запись в файл, а ваше приложение пытается изменить файл. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientFilePermissions",
"message": "The user does not have sufficient permissions for file {fileId}."
}
],
"code": 403,
"message": "The user does not have sufficient permissions for file {fileId}."
}
}
Чтобы исправить эту ошибку, попросите пользователя связаться с владельцем файла и запросить доступ для редактирования. Вы также можете проверить уровни доступа пользователей в метаданных, полученных методом files.get
, и отобразить пользовательский интерфейс только для чтения, если разрешения отсутствуют.
myDriveHierarchyDepthLimitExceeded
Ошибка myDriveHierarchyDepthLimitExceeded
возникает, когда превышен лимит на количество уровней вложенности папок. Мой диск пользователя не может содержать более 100 уровней вложенности папок. Для получения дополнительной информации см. Ограничение на глубину папки .
{
"error": {
"errors": [
{
"domain": "global",
"reason": "myDriveHierarchyDepthLimitExceeded",
"message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/workspace/drive/api/guides/handle-errors#nested-folder-levels."
}
],
"code": 403,
"message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/workspace/drive/api/guides/handle-errors#nested-folder-levels."
}
}
Чтобы исправить эту ошибку:
- Сообщите пользователю, что Диск не позволяет размещать папки глубиной более 100 уровней.
- Если пользователю необходимо создать еще одну вложенную папку, попросите его реорганизовать предполагаемую родительскую папку так, чтобы ее глубина была менее 100 уровней, или использовать другую родительскую папку, которая уже соответствует этому требованию.
numChildrenInNonRootLimitExceeded
Эта ошибка возникает, когда превышен лимит на количество дочерних элементов папки (папок, файлов и ярлыков). Для папок, файлов и ярлыков, находящихся непосредственно в папке, существует лимит в 500 000 элементов. Элементы, вложенные в подпапки, не учитываются в этом лимите в 500 000 элементов. Для получения дополнительной информации об ограничениях папок Диска см. Ограничения папок в Google Диске .
Следующий пример JSON представляет собой представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "numChildrenInNonRootLimitExceeded",
"message": "The limit for this folder's number of children (files and folders) has been exceeded."
}
],
"code": 403,
"message": "The limit for this folder's number of children (files and folders) has been exceeded."
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
- Сообщите пользователю, что Диск не допускает создания папок, содержащих более 500 000 элементов.
- Если пользователю необходимо добавить больше элементов в полную папку, попросите его реорганизовать папку так, чтобы она содержала менее 500 000 элементов, или использовать похожую папку, которая уже содержит меньше элементов.
rateLimitExceeded
Эта ошибка возникает, когда достигнут предел скорости проекта. Этот предел зависит от типа запроса. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
- Увеличьте квоту на пользователя в проекте Google Cloud. Для получения дополнительной информации запросите увеличение квоты .
- Пакетные запросы для объединения нескольких вызовов API в один HTTP-запрос.
- Используйте экспоненциальную задержку для повторной попытки запроса.
sharingRateLimitExceeded
Эта ошибка возникает, когда пользователь достигает лимита обмена и часто связана с лимитом электронной почты. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"message": "Rate limit exceeded. User message: \"These item(s) could not be shared because a rate limit was exceeded: filename",
"reason": "sharingRateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Чтобы исправить эту ошибку:
- Не отправляйте электронные письма, если вам нужно поделиться большим объемом файлов.
- Если один пользователь делает многочисленные запросы от имени многих пользователей учетной записи Google Workspace, рассмотрите возможность использования служебной учетной записи с делегированием на уровне домена с использованием параметра
quotaUser
.
storageQuotaExceeded
Эта ошибка возникает, когда пользователь достигает своего лимита хранилища. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"message": "The user's Drive storage quota has been exceeded.",
"reason": "storageQuotaExceeded",
}
],
"code": 403,
"message": "The user's Drive storage quota has been exceeded."
}
}
Чтобы исправить эту ошибку:
Проверьте лимиты хранилища вашего аккаунта Drive. Для получения дополнительной информации см. Ограничения хранилища и загрузки Google Workspace .
teamDriveFileLimitExceeded
Эта ошибка возникает, когда пользователь пытается превысить строгий лимит элементов на общем диске. Каждая папка на общем диске пользователя имеет лимит в 500 000 элементов, включая файлы, папки и ярлыки. Этот лимит основан на количестве элементов, а не на использовании хранилища. Для получения дополнительной информации см. Ограничения на общие диски в Google Диске .
Следующий пример JSON представляет собой представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "teamDriveFileLimitExceeded",
"message": "The file limit for this shared drive has been exceeded."
}
],
"code": 403,
"message": "The file limit for this shared drive has been exceeded."
}
}
Чтобы исправить эту ошибку, уменьшите количество элементов на общем диске. Общие диски со слишком большим количеством файлов могут быть сложны для организации и поиска.
teamDriveHierarchyTooDeep
Ошибка teamDriveHierarchyTooDeep
возникает, когда превышен лимит на количество уровней вложенности папок общего диска. Общий диск пользователя не может содержать более 100 уровней вложенности папок. Для получения дополнительной информации см. Ограничение на глубину папки .
{
"error": {
"errors": [
{
"domain": "global",
"reason": "teamDriveHierarchyTooDeep",
"message": "The shared drive hierarchy depth will exceed the limit."
}
],
"code": 403,
"message": "The shared drive hierarchy depth will exceed the limit."
}
}
Чтобы исправить эту ошибку:
- Сообщите пользователю, что общие диски не позволяют размещать папки глубиной более 100 уровней.
- Если пользователю необходимо создать еще одну вложенную папку, попросите его реорганизовать предполагаемую родительскую папку так, чтобы ее глубина была менее 100 уровней, или использовать другую родительскую папку, которая уже соответствует этому требованию.
teamDriveMembershipRequired
Эта ошибка возникает, когда пользователь пытается получить доступ к общему диску, членом которого он не является. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "teamDriveMembershipRequired",
"message": "The attempted action requires shared drive membership."
}
],
"code": 403,
"message": "The attempted action requires shared drive membership."
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
Попросите менеджера общего диска добавить вас с соответствующими разрешениями для действия, которое вам необходимо выполнить.
Ознакомьтесь с ролями и разрешениями Drive, чтобы узнать, кто может получать доступ к общим дискам и управлять ими. Дополнительную информацию об уровнях доступа можно также найти в разделе Создание общего диска .
teamDrivesFolderMoveInNotSupported
Эта ошибка возникает, когда пользователь пытается переместить папку из My Drive на общий диск. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "teamDrivesFolderMoveInNotSupported",
"message": "Moving folders into shared drives is not supported."
}
],
"code": 403,
"message": "Moving folders into shared drives is not supported."
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
Переместите отдельные элементы из папки на общий диск с помощью API Drive. Установите параметр
supportsAllDrives=true
чтобы обозначить поддержку как My Drive, так и общих дисков.Если вам необходимо переместить папку на общий диск, используйте пользовательский интерфейс Drive. Для получения дополнительной информации см. Перемещение папок на общие диски в качестве администратора .
teamDrivesParentLimit
Эта ошибка возникает, когда пользователь пытается добавить более одного родителя к элементу на общем диске. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "teamDrivesParentLimit",
"message": "A shared drive item must have exactly one parent."
}
],
"code": 403,
"message": "A shared drive item must have exactly one parent."
}
}
Чтобы исправить эту ошибку, используйте ярлыки Диска, чтобы добавить несколько ссылок на файл. Хотя ярлык может иметь только одного родителя, файл ярлыка можно скопировать в дополнительные расположения. Для получения дополнительной информации см. раздел Создание ярлыка для файла Диска .
UrlLeaseLimitExceeded
Эта ошибка возникает при попытке сохранить данные игры Google Play через ваше приложение. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "UrlLeaseLimitExceeded",
"message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
}
],
"code": 403,
"message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
}
}
Чтобы исправить эту ошибку, завершите или отмените все загрузки снимка, прежде чем создавать новые.
userRateLimitExceeded
Эта ошибка возникает, когда достигнут предел для пользователя. Это может быть предел из консоли Google Cloud или предел из бэкэнда Drive. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Чтобы исправить эту ошибку, попробуйте выполнить любое из следующих действий:
Увеличьте квоту на пользователя в проекте Google Cloud. Для получения дополнительной информации запросите увеличение квоты .
Если один пользователь делает многочисленные запросы от имени многих пользователей учетной записи Google Workspace, рассмотрите возможность использования служебной учетной записи с делегированием на уровне домена с использованием параметра
quotaUser
.Используйте экспоненциальную задержку для повторной попытки запроса.
Информацию об ограничениях API Drive см. в разделе Ограничения на использование .
404 ошибки
Эти ошибки означают, что запрошенный ресурс недоступен или не существует.
notFound
Эта ошибка возникает, когда у пользователя нет прав на чтение файла или файл не существует. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "File not found {fileId}"
}
],
"code": 404,
"message": "File not found: {fileId}"
}
}
Чтобы исправить эту ошибку:
- Если файл находится на общем диске и вы используете метод
files.get
, убедитесь, что параметр запросаsupportsAllDrives
имеет значениеtrue
. - Сообщите пользователю, что у него нет прав на чтение файла или файл не существует.
- Попросите пользователя связаться с владельцем файла и запросить разрешение на доступ к файлу.
429 ошибок
Эти ошибки означают, что слишком много запросов было отправлено в API слишком быстро.
rateLimitExceeded
Эта ошибка возникает, когда пользователь отправил слишком много запросов за определенный промежуток времени. Следующий пример JSON представляет эту ошибку:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "rateLimitExceeded",
"message": "Rate Limit Exceeded"
}
],
"code": 429,
"message": "Rate Limit Exceeded"s
}
}
Чтобы исправить эту ошибку, используйте экспоненциальную задержку для повторной попытки запроса.
Ошибки 500, 502, 503, 504
Эти ошибки возникают, когда при обработке запроса возникает непредвиденная ошибка сервера. Различные проблемы могут вызывать эти ошибки, включая перекрытие времени запроса с другим запросом или запрос на неподдерживаемое действие, например, попытка обновить разрешения для одной страницы в Google Sites вместо всего сайта.
Ниже приведен список ошибок 5xx:
- 500 Ошибка бэкэнда
- 502 Неверный шлюз
- 503 Служба недоступна
- 504 Тайм-аут шлюза
Чтобы исправить эту ошибку, используйте экспоненциальную задержку для повторной попытки запроса.