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 字段并相应地调整代码。
illegalKeepForeverModification
尝试将标记为“永久保留”的 blob 文件修订版本设置为 false 时,会发生此错误。以下 JSON 示例表示了此错误:
{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "illegalKeepForeverModification",
    "message": "Bad Request. Cannot update a revision to false that is marked as keepForever."
   }
  ],
  "code": 400,
  "message": "Bad Request. Cannot update a revision to false that is marked as keepForever."
 }
}
如需修正此错误,请永久删除某个 blob 文件修订版本,以移除“永久保留”设置。
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"
  }
}
如需修正此错误,请使用长期有效的刷新令牌刷新访问令牌。如果此操作失败,请按照选择 Google Drive API 范围中所述,引导用户完成 OAuth 流程。
fileNotDownloadable
当您尝试在 Google Workspace 文档上使用带有 alt=media 网址参数的 revisions.get 方法时,会发生此错误。以下 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."
  }
}
如需修正此错误,请尝试执行以下任一操作:
- 如果您想查看特定修订版本的元数据(例如 MIME 类型),请移除 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 资源,以查看此共享云端硬盘内容的权限是继承的还是直接应用的。
dailyLimitExceeded
当项目达到 API 限制时,就会发生此错误。以下 JSON 示例表示了此错误:
{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}
当应用所有者设置了配额限制来限制特定资源的使用时,系统会显示此错误。如需修正此错误,请移除“每日查询次数”配额的所有用量上限。
domainPolicy
如果用户的网域政策不允许您的应用访问 Google 云端硬盘,就会出现此错误。以下 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."
  }
}
如需修正此错误,请执行以下操作:
- 告知用户网域不允许您的应用访问 Google 云端硬盘中的文件。
- 指示用户与网域管理员联系,以请求为您的应用授予访问权限。
downloadRestrictedForRevision
当用户无法下载 blob 文件修订版本时,会发生此错误。以下 JSON 示例表示此错误:
{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "download_restricted_for_revision",
        "message": "This revision cannot be downloaded by the authenticated user."
      }
    ],
    "code": 403,
    "message": "This revision cannot be downloaded by the authenticated user."
  }
}
如需修正此错误,请告知用户,只有当 blob 文件修订版本标记为“永久保留”时,才能下载这些修订版本。如需了解详情,请参阅指定要保存的修订版本,以免被自动删除。
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/workspace/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/workspace/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"
 }
}
如需修正此错误,请尝试执行以下任一操作:
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 存储空间和上传限制。 
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 控制台的限制,也可能是 Google 云端硬盘后端的限制。以下 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 Sites 中单个网页(而非整个网站)的权限。
以下是 5xx 错误的列表:
- 500 后端错误
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
如需修正此错误,请使用指数退避算法重试请求。