解决错误

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 亿个项。如需了解详情,请参阅 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 万项。嵌套在子文件夹中的项不会计入此 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"
 }
}

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

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 云端硬盘存储空间中的文件

  3. 购买更多 Google 存储空间

teamDriveFileLimitExceeded

如果用户尝试超出对共享云端硬盘的严格内容限制,就会出现此错误。用户共享云端硬盘中每个文件夹最多可包含 40 万项内容,包括文件、文件夹和快捷方式。此限额取决于内容数量,而非存储空间用量。如需了解详情,请参阅 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."
  }
}

如需修正此错误,请减少共享云端硬盘中的内容数量。包含过多文件的共享云端硬盘可能难以整理和搜索。

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

当您尝试通过您的应用保存 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 项目中每位用户的配额。如需了解详情,请申请增加配额

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

404 错误

这些错误意味着所请求的资源无法访问或不存在。

notFound

如果用户没有文件的读取权限,或文件不存在,就会出现此错误。以下 JSON 示例展示了此错误:

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

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

  1. 通知用户,他们没有该文件的读取权限,或该文件不存在。
  2. 指示用户联系文件的所有者并请求文件权限。

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

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