解决错误

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

要修正此错误,请执行以下操作:

  1. 告知用户云端硬盘禁止创建账号 超过 5 亿个项目。

  2. 如果用户必须在此同一账号中创建商品,请指导他们 永久删除某些对象。否则,他们可以使用其他账号 已满足要求

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

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

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

要修正此错误,请执行以下操作:

  1. 告知用户该网域不允许您的应用访问 云端硬盘。
  2. 指示用户联系域管理员申请访问权限 。

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

要修正此错误,请执行以下操作:

  1. 将该成员与role=owner一起添加到共享云端硬盘。如需更多信息 请参阅共享文件、文件夹和云端硬盘

  2. 将文件添加到共享云端硬盘。有关详情,请参阅创建和 填充文件夹

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

要修正此错误,请执行以下操作:

  1. 告知用户,云端硬盘禁止放置的文件夹数量超过 共 100 层,
  2. 如果用户必须再创建一个嵌套文件夹,请指导他们重新整理 目标父级文件夹的深度少于 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"
 }
}

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

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

要修正此错误,请执行以下操作:

  1. 共享大量文件时不发送电子邮件。
  2. 如果某位用户代表某个网站的多个用户 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."
 }
}

要修正此错误,请执行以下操作:

  1. 查看您的云端硬盘存储空间限制。有关 请参阅 Google Workspace 存储空间和上传 限制

  2. 管理 Google 云端硬盘中的文件 storage

  3. 购买更多 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."
 }
}

要修正此错误,请执行以下操作:

  1. 告知用户,共享云端硬盘禁止放置的文件夹数量超过 共 100 层,
  2. 如果用户必须再创建一个嵌套文件夹,请指导他们重新整理 目标父级文件夹的深度少于 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."
  }
}

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

  1. 请让共享云端硬盘的管理员将您添加相应的 必须执行的操作的权限。

  2. 查看云端硬盘的角色和 权限,以了解谁可以访问和管理 共享云端硬盘。您还可以找到有关访问权限级别的更多信息 创建共享 云端硬盘

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

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

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

404 错误

这些错误表示所请求的资源无法访问或不存在。

notFound

如果用户没有文件的读取权限,或文件 不存在。以下 JSON 示例是此错误的表示形式:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "File not found {fileId}"
      }
    ],
    "code": 404,
    "message": "File not found: {fileId}"
  }
}

要修正此错误,请执行以下操作:

  1. 如果文件位于共享云端硬盘中,并且您使用的是 files.get 方法,请确保 supportsAllDrives 查询参数设置为 true
  2. 告知用户他们没有相应文件或文件的读取权限 不存在。
  3. 指示用户联系文件所有者并请求对 文件。

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

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