此页面由 Cloud Translation API 翻译。

解决错误

Google Drive API 返回两个级别的错误信息：

HTTP 错误代码和标头消息。
响应正文中的 JSON 对象，包含可以帮助您使用的更多详细信息以确定如何处理错误。

Google 云端硬盘应用应捕捉并处理可能遇到的所有错误。本指南介绍了如何解决特定的 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`

导致此错误的原因有很多。要确定原因，请评估所返回的 JSON 的 reason 字段。出现此错误最常见的原因是：

共享成功，但是通知电子邮件未正确递送。
不允许此用户更改访问控制列表 (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@domain.com.\""
      }
    ],
    "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 流程，如选择 Google Drive API 作用域。

403 错误

这些错误表示超出了使用量限额，或者用户适当的权限要确定原因，请评估reason 返回的 JSON。

如要了解 Drive API 限制，请参阅用量限额。有关云端硬盘文件夹的信息请参阅文件和文件夹限制。

`activeItemCreationLimitExceeded`

数量限制发生时，会发生activeItemCreationLimitExceeded错误。已超过每个账号创建的商品数量上限。每位用户最多可以创建的超过 100 万个项。有关详情，请参阅 User-item 限制。

{
 "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."
 }
}

要修正此错误，请执行以下操作：

告知用户云端硬盘禁止创建账号超过 5 亿个项目。
如果用户必须在此同一账号中创建商品，请指导他们永久删除某些对象。否则，他们可以使用其他账号已满足要求

`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`

如果用户网域的政策不允许访问使用您的应用。以下 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/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/drive/api/guides/handle-errors#nested-folder-levels."
 }
}

要修正此错误，请执行以下操作：

告知用户，云端硬盘禁止放置的文件夹数量超过共 100 层，
如果用户必须再创建一个嵌套文件夹，请指导他们重新整理目标父级文件夹的深度少于 100 层，或使用已满足要求的其他父级文件夹

`numChildrenInNonRootLimitExceeded`

当文件夹的子文件夹（文件夹、文件和快捷方式）数量超出了上限。商品数量上限为 50 万件文件夹、文件和文件夹。嵌套在子文件夹中的内容不会计入 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."
 }
}

如需修正此错误，请尝试执行以下任一操作：

告知用户，云端硬盘不得使用超过 50 万项内容。
如果用户必须向整个文件夹添加更多项目，请指导他们请重新组织该文件夹，使其包含的内容少于 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."
 }
}

要修正此错误，请执行以下操作：

查看您的云端硬盘存储空间限制。有关请参阅 Google Workspace 存储空间和上传限制。
管理 Google 云端硬盘中的文件 storage。
购买更多 Google 产品 storage。

`teamDriveFileLimitExceeded`

如果用户试图超过在 Google Play 商店中销售的共享云端硬盘。用户的共享云端硬盘中每个文件夹的内容上限为 50 万项，包括文件、文件夹和快捷方式。此上限基于项数，而不是存储空间使用情况有关详情，请参阅 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."
  }
}

如需修正此错误，请尝试执行以下任一操作：

请让共享云端硬盘的管理员将您添加相应的必须执行的操作的权限。
查看云端硬盘的角色和权限，以了解谁可以访问和管理共享云端硬盘。您还可以找到有关访问权限级别的更多信息创建共享云端硬盘。

`teamDrivesFolderMoveInNotSupported`

如果用户尝试将文件夹从“我的文件夹”中移出，就会出现此错误将云端硬盘移动到共享云端硬盘。以下 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."
  }
}

如需修正此错误，请尝试执行以下任一操作：

使用 Drive API。设置 supportsAllDrives=true 形参以指明支持“我的云端硬盘”和共享云端硬盘。
如果您必须将该文件夹移至共享云端硬盘，请使用云端硬盘界面。有关详情，请参阅将文件夹移至共享文件夹管理云端硬盘。

`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`

当您尝试通过您的应用。以下 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 控制台中的上限，或者云端硬盘的限制后端。以下 JSON 示例是此错误的表示形式：

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

如需修正此错误，请尝试执行以下任一操作：

提高 Google Cloud 项目中每位用户的配额。如需更多信息申请增加配额。
如果某位用户代表某个网站的多个用户 Google Workspace 账号，请考虑使用全网域服务账号委托使用quotaUser 参数。
使用指数退避算法重试请求。

如要了解 Drive API 限制，请参阅用量限额。

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
  }
}

要修正此错误，请使用指数通过 backoff 重试请求。

500、502、503、504 错误

如果在处理请求。各种问题都可能会导致这些错误，包括请求的时间安排与其他请求重叠或请求不受支持的操作，例如尝试更新 Google 协作平台中单个页面的权限，而不是更新访问整个网站。

以下是 5xx 错误列表：

500 后端错误
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

要修正此错误，请使用指数退避算法以重试请求。

解决错误

HTTP 状态代码摘要

400 错误

badRequest

invalidSharingRequest

分享成功，但通知电子邮件未正确递送

此用户无权更改 ACL

401 错误

authError

403 错误

activeItemCreationLimitExceeded

appNotAuthorizedToFile

cannotModifyInheritedTeamDrivePermission

dailyLimitExceeded

domainPolicy

fileOwnerNotMemberOfTeamDrive

fileWriterTeamDriveMoveInDisabled

insufficientFilePermissions

myDriveHierarchyDepthLimitExceeded

numChildrenInNonRootLimitExceeded

rateLimitExceeded

sharingRateLimitExceeded

storageQuotaExceeded

teamDriveFileLimitExceeded

teamDriveHierarchyTooDeep

teamDriveMembershipRequired

teamDrivesFolderMoveInNotSupported

teamDrivesParentLimit

UrlLeaseLimitExceeded

userRateLimitExceeded

404 错误

notFound

429 错误

rateLimitExceeded

500、502、503、504 错误

相关主题

`badRequest`

`invalidSharingRequest`

`authError`

`activeItemCreationLimitExceeded`

`appNotAuthorizedToFile`

`cannotModifyInheritedTeamDrivePermission`

`dailyLimitExceeded`

`domainPolicy`

`fileOwnerNotMemberOfTeamDrive`

`fileWriterTeamDriveMoveInDisabled`

`insufficientFilePermissions`

`myDriveHierarchyDepthLimitExceeded`

`numChildrenInNonRootLimitExceeded`

`rateLimitExceeded`

`sharingRateLimitExceeded`

`storageQuotaExceeded`

`teamDriveFileLimitExceeded`

`teamDriveHierarchyTooDeep`

`teamDriveMembershipRequired`

`teamDrivesFolderMoveInNotSupported`

`teamDrivesParentLimit`

`UrlLeaseLimitExceeded`

`userRateLimitExceeded`

`notFound`

`rateLimitExceeded`