解決錯誤

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 文件上使用 revisions.get 方法和 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."
  }
}

如要修正這項錯誤,請嘗試下列任一方法:

  • 如要查看特定修訂版本的 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."
 }
}

如要修正這項錯誤,請按照下列步驟操作:

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

如要修正這項錯誤,請嘗試下列任一方法:

  • 開啟 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."
  }
}

如要修正這項錯誤,請按照下列步驟操作:

  1. 告知使用者網域不允許應用程式存取雲端硬碟中的檔案。
  2. 請使用者與網域管理員聯絡,要求授予應用程式存取權。

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

如要修正這項錯誤,請按照下列步驟操作:

  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 方法擷取的中繼資料中,檢查使用者存取層級,並在缺少權限時顯示唯讀 UI。

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

如要修正這項錯誤,請按照下列步驟操作:

  1. 告知使用者雲端硬碟禁止放置超過 100 層的資料夾。
  2. 如果使用者必須建立另一個巢狀資料夾,請指示他們重新整理預期的上層資料夾,使其深度少於 100 層,或使用已符合規定的其他上層資料夾。

numChildrenInNonRootLimitExceeded

如果資料夾的子項 (資料夾、檔案和捷徑) 數量超過上限,就會發生這項錯誤。資料夾、檔案和捷徑直接存入資料夾的項目上限為 500,000 個。子資料夾中的項目不會計入這項 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 萬個項目的資料夾。
  • 如果使用者必須在完整資料夾中新增更多項目,請指示他們重新整理資料夾,確保項目數量少於 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 雲端硬碟、Gmail 和 Google 相簿的儲存空間

  3. 購買更多 Google 儲存空間

teamDriveFileLimitExceeded

如果使用者嘗試在共用雲端硬碟中新增超過嚴格項目限制的項目,就會發生這個錯誤。在共用雲端硬碟中,每個資料夾最多可以有 500,000 個項目, 包括檔案、資料夾和捷徑。這項限制是以商品數量為依據,而非儲存空間使用量。詳情請參閱「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. 請參閱 Google 雲端硬碟的角色和權限,瞭解誰可以存取及管理共用雲端硬碟。如需存取層級的相關資訊,請參閱「建立共用雲端硬碟」一文。

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

如要修正這項錯誤,請嘗試下列任一方法:

如要瞭解 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
  }
}

如要修正這項錯誤,請使用指數輪詢重試要求。

500、502、503、504 錯誤

處理要求時發生未預期的伺服器錯誤,就會導致這類錯誤。造成這些錯誤的原因有很多,包括要求時間與其他要求重疊,或是要求執行不支援的動作,例如嘗試更新 Google 協作平台中單一網頁的權限,而非整個網站。

以下列出 5xx 錯誤:

  • 500 後端錯誤
  • 502 閘道錯誤
  • 503 無法提供服務
  • 504 閘道逾時

如要修正這項錯誤,請使用指數輪詢重試要求。