本頁面由 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 範圍」一節所述。

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 雲端硬碟選擇器，並提示使用者開啟檔案。
在應用程式的雲端硬碟使用者介面中，利用「Open with」(開啟方式) 內容選單指示使用者開啟檔案。
使用 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 方法擷取的中繼資料，查看使用者存取層級，並在缺少權限時顯示唯讀 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/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`

如果超過資料夾的子項 (資料夾、檔案和捷徑) 數量限制，就會發生此錯誤。資料夾、檔案和捷徑的項目數量上限為 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."
 }
}

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

通知使用者，雲端硬碟已禁止含有超過 500,000 個項目的資料夾。
如果使用者必須將更多項目新增至完整資料夾，請指示使用者重新整理資料夾，使其包含的項目少於 500,000 個，或者改用包含較少項目的類似資料夾。

`rateLimitExceeded`

如果達到專案的頻率限制，就會發生這個錯誤。這項限制會因要求類型而異。以下 JSON 範例說明這個錯誤：

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

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

提高 Google Cloud 專案中每位使用者的配額。詳情請參閱要求增加配額。
批次要求可減少 API 呼叫次數。
請使用指數輪詢重試要求。

`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`

如果使用者嘗試超過共用雲端硬碟的項目限制，就會發生這項錯誤。使用者共用雲端硬碟中的每個資料夾最多只能有 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."
  }
}

如要修正這項錯誤，請減少共用雲端硬碟中的項目數量。檔案過多的共用雲端硬碟可能會難以整理及搜尋。

`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 參數以表示支援「我的雲端硬碟」和共用雲端硬碟。
如果您必須將資料夾移至共用雲端硬碟，請使用雲端硬碟 UI。詳情請參閱「以管理員身分將資料夾移至共用雲端硬碟」。

`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 專案中每位使用者的配額。詳情請參閱要求增加配額。

如果某位使用者代表 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 閘道錯誤
503 服務無法使用
504 閘道逾時

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

解決錯誤

HTTP 狀態碼摘要

400 錯誤

badRequest

invalidSharingRequest

分享成功，但通知電子郵件未正確送達

不允許這位使用者變更 ACL

401 錯誤

authError

403 錯誤

activeItemCreationLimitExceeded

appNotAuthorizedToFile

cannotModifyInheritedTeamDrivePermission

dailyLimitExceeded

domainPolicy

fileOwnerNotMemberOfTeamDrive

fileWriterTeamDriveMoveInDisabled

insufficientFilePermissions

myDriveHierarchyDepthLimitExceeded

numChildrenInNonRootLimitExceeded

rateLimitExceeded

sharingRateLimitExceeded

storageQuotaExceeded

teamDriveFileLimitExceeded

teamDriveMembershipRequired

teamDrivesFolderMoveInNotSupported

teamDrivesParentLimit

UrlLeaseLimitExceeded

userRateLimitExceeded

404 錯誤

notFound

429 錯誤

rateLimitExceeded

500、502、503、504 錯誤

相關主題

`badRequest`

`invalidSharingRequest`

`authError`

`activeItemCreationLimitExceeded`

`appNotAuthorizedToFile`

`cannotModifyInheritedTeamDrivePermission`

`dailyLimitExceeded`

`domainPolicy`

`fileOwnerNotMemberOfTeamDrive`

`fileWriterTeamDriveMoveInDisabled`

`insufficientFilePermissions`

`myDriveHierarchyDepthLimitExceeded`

`numChildrenInNonRootLimitExceeded`

`rateLimitExceeded`

`sharingRateLimitExceeded`

`storageQuotaExceeded`

`teamDriveFileLimitExceeded`

`teamDriveMembershipRequired`

`teamDrivesFolderMoveInNotSupported`

`teamDrivesParentLimit`

`UrlLeaseLimitExceeded`

`userRateLimitExceeded`

`notFound`

`rateLimitExceeded`