此页面由 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 权限范围中所述。

`fileNotDownloadable`

当您尝试将 revisions.get 方法与 Google Workspace 文档中的 alt=media 网址参数搭配使用时，会发生此错误。以下 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."
  }
}

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

如果您想查看特定修订版本的元数据（例如 mimetype），请移除 alt=media 网址参数。
使用 files.export 方法导出 Google Workspace 文档字节内容。如需了解详情，请参阅导出 Google Workspace 文档内容。

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 调用打包到一个 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 云端硬盘存储空间中的文件。
购买更多 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."
  }
}

如需解决此错误，请使用云端硬盘快捷方式向文件添加多个链接。虽然快捷方式只能有一个父级，但快捷方式文件可以复制到其他位置。如需了解详情，请参阅创建 Google 云端硬盘文件的快捷方式。

`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

fileNotDownloadable

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`

`fileNotDownloadable`

`activeItemCreationLimitExceeded`

`appNotAuthorizedToFile`

`cannotModifyInheritedTeamDrivePermission`

`dailyLimitExceeded`

`domainPolicy`

`fileOwnerNotMemberOfTeamDrive`

`fileWriterTeamDriveMoveInDisabled`

`insufficientFilePermissions`

`myDriveHierarchyDepthLimitExceeded`

`numChildrenInNonRootLimitExceeded`

`rateLimitExceeded`

`sharingRateLimitExceeded`

`storageQuotaExceeded`

`teamDriveFileLimitExceeded`

`teamDriveHierarchyTooDeep`

`teamDriveMembershipRequired`

`teamDrivesFolderMoveInNotSupported`

`teamDrivesParentLimit`

`UrlLeaseLimitExceeded`

`userRateLimitExceeded`

`notFound`

`rateLimitExceeded`