此页面由 Cloud Translation API 翻译。

解决错误

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

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

Google 云端硬盘应用应捕获并处理使用 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`

导致此错误的原因有很多。如需确定原因，请评估返回的 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 错误

这些错误表示超出了用量限额或用户没有正确的权限。如需确定原因，请评估返回的 JSON 的 reason 字段。

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

`activeItemCreationLimitExceeded`

如果超出了每个帐号创建的内容数量限制，就会发生 activeItemCreationLimitExceeded 错误。每个用户最多可以通过一个账号创建 5 亿件商品。如需了解详情，请参阅用户项限制。

{
 "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 方法检查 files 资源上的 isAppAuthorized 字段，以验证您的应用是否创建或打开了该文件。

`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 万项内容。嵌套在子文件夹中的内容不会计入 50 万项的限制。如需详细了解云端硬盘文件夹限制，请参阅 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 万项内容的文件夹。
如果用户必须向完整文件夹中添加更多项，请指导他们重新组织文件夹，使其包含的项少于 50 万个，或使用包含的项数较少的类似文件夹。

`rateLimitExceeded`

达到项目的速率限制时会发生此错误。此限制因请求类型而异。以下 JSON 示例是此错误的表示形式：

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

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

提高 Google Cloud 项目中每位用户的配额。如需了解详情，请申请增加配额。
批量请求，减少发出的 API 调用次数。
使用指数退避算法重试请求。

`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 云端硬盘存储空间中的文件。
购买更多 Google 存储空间。

`teamDriveFileLimitExceeded`

如果用户尝试超出共享云端硬盘的严格内容限制，就会出现此错误。用户的共享云端硬盘中每个文件夹的内容上限为 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`

当您尝试通过您的应用保存 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 控制台中的限制，也可能是云端硬盘后端的限制。以下 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
  }
}

如需修复此错误，请使用指数退避算法重试请求。

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`