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"
}
}
如要修正這項錯誤,請嘗試下列任一方法:
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
如果使用者嘗試超過共用雲端硬碟的項目限制,就會發生這項錯誤。使用者共用雲端硬碟中的每個資料夾最多只能有 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
}
}
如要修正這個錯誤,請使用指數輪詢重試要求。
500、502、503、504 錯誤
處理要求時發生未預期的伺服器錯誤,就會發生這些錯誤。各種問題可能會導致這類錯誤,包括要求的時間與其他要求重疊,或要求不支援的動作,例如嘗試更新 Google 協作平台中單一網頁的權限,而非更新整個網站的權限。
以下列出 5xx 錯誤:
- 500 後端錯誤
- 502 閘道錯誤
- 503 服務無法使用
- 504 閘道逾時
如要修正這個錯誤,請使用指數輪詢重試要求。