本頁面由 Cloud Translation API 翻譯而成。

解決錯誤

Google Drive API 會傳回兩種錯誤資訊：

HTTP 錯誤代碼和標頭訊息。
回應主體中的 JSON 物件，含有額外的詳細資料，有助您以確定如何處理錯誤。

Google 雲端硬碟應用程式應能找出並處理所有可能發生的錯誤來解決您的疑慮本指南說明如何解決雲端硬碟 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`

這個錯誤發生的原因有很多。如要找出原因，請評估 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 錯誤數量已超出單一帳戶建立的項目數量。每位使用者最多可以有 500 個 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."
 }
}

如何修正這項錯誤：

請通知使用者，雲端硬碟禁止建立帳戶超過 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 方法：檢查 isAppAuthorized 欄位 files 資源，可驗證已建立或開啟檔案的應用程式。

`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 雲端硬碟中的檔案如果 30 天內讀取資料不到一次建議使用 Nearline Storage
購買更多 Google 服務如果 30 天內讀取資料不到一次建議使用 Nearline Storage

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

如何修正這項錯誤：

請通知使用者，共用雲端硬碟最多只能放置超過有 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 參數以表示同時支援「我的雲端硬碟」和共用雲端硬碟。
如果您必須將資料夾移至共用雲端硬碟，請使用雲端硬碟 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
  }
}

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

500、502、503、504 錯誤

處理伺服器時發生未預期的伺服器錯誤，請求。各種問題都可能造成這些錯誤，包括要求的處理時間與其他要求重疊，或已請求不支援的動作，例如嘗試更新 Google 協作平台中單一頁面的權限，而非或整個網站

以下列出 5xx 錯誤：

500 後端錯誤
502 閘道錯誤
503 服務無法使用
504 閘道逾時

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

解決錯誤

HTTP 狀態碼摘要

400 錯誤

badRequest

invalidSharingRequest

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

不允許這位使用者變更 ACL

401 錯誤

authError

403 錯誤

activeItemCreationLimitExceeded

appNotAuthorizedToFile

cannotModifyInheritedTeamDrivePermission

dailyLimitExceeded

domainPolicy

fileOwnerNotMemberOfTeamDrive

fileWriterTeamDriveMoveInDisabled

insufficientFilePermissions

myDriveHierarchyDepthLimitExceeded

numChildrenInNonRootLimitExceeded

rateLimitExceeded

sharingRateLimitExceeded

storageQuotaExceeded

teamDriveFileLimitExceeded

teamDriveHierarchyTooDeep

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`

`teamDriveHierarchyTooDeep`

`teamDriveMembershipRequired`

`teamDrivesFolderMoveInNotSupported`

`teamDrivesParentLimit`

`UrlLeaseLimitExceeded`

`userRateLimitExceeded`

`notFound`

`rateLimitExceeded`