Resolve errors  |  Google Drive  |  Google for Developers (2024)

The Google Drive API returns two levels of error information:

• HTTP error codes and header messages.
• A JSON object in the response body with additional details that can help youdetermine how to handle the error.

Google Drive apps should catch and handle all errors that might be encounteredwhen using the REST API. This guide provides instructions about how to resolvespecific Drive API errors.

HTTP status code summary

400 errors

These errors mean that the request was unacceptable, often due to a missingrequired parameter.

badRequest

This error can occur from any one of the following issues in your code:

• A required field or parameter hasn't been provided.
• The value supplied or a combination of provided fields is invalid.
• You tried to add a duplicate parent to a Drive file.
• You tried to add a parent that would create a cycle in the directory graph.

The following JSON sample is a representation of this error:

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

To fix this error, check the message field and adjust your code accordingly.

invalidSharingRequest

This error occurs for several reasons. To determine the cause, evaluate thereason field of the returned JSON. This error most commonly occurs because:

• Sharing succeeded, but the notification email wasn't correctly delivered.
• The Access Control List (ACL) change isn't allowed for this user.

The message field indicates the actual error.

The following JSON sample is a representation of this error:

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

To fix this error, inform the user (sharer) they were unable to share becausethe notification email couldn't be sent to the destination email address. Theuser should make sure they have the correct email address and that it canreceive email.

The ACL change isn't allowed for this user

The following JSON sample is a representation of this error:

{ "error": { "errors": [ { "domain": "global", "reason": "invalidSharingRequest", "message": "Bad Request. User message: \"ACL change not allowed.\"" } ], "code": 400, "message": "Bad Request" }}

To fix this error, check the sharingsettings of the Google Workspace domain to which the file belongs. The settings mightprohibit sharing outside of the domain or sharing a shared drive might not bepermitted.

401 errors

These errors mean the request doesn't contain a valid access token.

authError

This error occurs when the access token that you're using is either expired orinvalid. This error can also be caused by missing authorization for therequested scopes. The following JSON sample is a representation of this error:

{ "error": { "errors": [ { "domain": "global", "reason": "authError", "message": "Invalid Credentials", "locationType": "header", "location": "Authorization", } ], "code": 401, "message": "Invalid Credentials" }}

To fix this error, refresh the access token using the long-lived refresh token.If this fails, direct the user through the OAuth flow, as described in ChooseGoogle Drive API scopes.

fileNotDownloadable

This error occurs when you try to use the revisions.get method with thealt=media URL parameter on a Google Workspace document. The following JSONsample is a representation of this error:

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

To fix this error, try any of the following:

• Remove the alt=media URL parameter if you want to view the metadata of aparticular revision, such as the mimetype.
• Use the files.export method to export Google Workspace document bytecontent. For more information, see Export Google Workspace documentcontent.

403 errors

These errors mean that a usage limit has been exceeded or the user doesn't havethe correct privileges. To determine the cause, evaluate the reason field ofthe returned JSON.

For information about Drive API limits, refer to Usage limits. For information about Drive folderlimits, refer to File and folder limits.

activeItemCreationLimitExceeded

An activeItemCreationLimitExceeded error occurs when the limit for the numberof items created per account has been exceeded. Each user can have up to 500million items created by an account. For more information, see User-itemlimit.

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

To fix this error:

1. Inform the user that Drive prevents accounts from creatingmore than 500 million items.

2. If the user must create items in this same account, instruct them topermanently delete some objects. Otherwise, they can use a different accountthat already meets the requirement.

appNotAuthorizedToFile

This error occurs when your app isn't on the ACL for the file. This errorprevents the user from opening the file with your app. The following JSON sampleis a representation of this error:

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

To fix this error, try any of the following:

• Open the Google Drive pickerand prompt the user to open the file.
• Instruct the user to open the file using the Open with context menu in the DriveUI of your app.
• Use the files.get method tocheck the isAppAuthorized field on thefiles resource to verify that yourapp created or opened the file.

This error occurs when a user tries to modify the inherited permissions of anitem within a shared drive. Inherited permissions can't be removed from an itemin a shared drive. The following JSON sample is a representation of this error:

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

To fix this error, a user must adjust the permissions on the direct or indirectparent item from which they were inherited. For more information, seePermissionpropagation. You canalso retrieve thepermissions.permissionDetailsresource to see whether the permissions on this shared drive item are inheritedor applied directly.

dailyLimitExceeded

This error occurs when the API limit for your project was reached. The followingJSON sample is a representation of this error:

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

This error appears when the application's owner has set a quota limit to capusage of a particular resource. To fix this error, remove any usage caps forthe "Queries per day"quota.

domainPolicy

This error occurs when the policy for the user's domain doesn't allow access toDrive by your app. The following JSON sample is a representationof this error:

{ "error": { "errors": [ { "domain": "global", "reason": "domainPolicy", "message": "The domain administrators have disabled Drive apps." } ], "code": 403, "message": "The domain administrators have disabled Drive apps." }}

To fix this error:

1. Inform the user that the domain doesn't allow your app to access files inDrive.
2. Instruct the user to contact the domain administrator to request access foryour app.

This error occurs when attempting to move a file into a shared drive and thefile owner isn't a member. The following JSON sample is a representation of thiserror:

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

To fix this error:

1. Add the member to the shared drive with role=owner. For more information,see Share files, folders, and drives.

2. Add the file to the shared drive. For more information, see Create andpopulate folders.

This error occurs when a domain administrator hasn't allowed users withrole=writer to move items into a shared drive. The user attempting to move theitems has fewer permissions than allowed on the destination shared drive. Thefollowing JSON sample is a representation of this error:

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

To fix this error, use the same administrator user account on both the sourceand destination shared drives.

insufficientFilePermissions

This error occurs when the user doesn't have write access to a file, and yourapp is attempting to modify the file. The following JSON sample is arepresentation of this error:

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

To fix this error, instruct the user to contact the file's owner and requestedit access. You can also check user access levels in the metadata retrieved bythe files.get method and display aread-only UI when permissions are missing.

myDriveHierarchyDepthLimitExceeded

A myDriveHierarchyDepthLimitExceeded error occurs when the limit for thenumber of nested folder levels has been exceeded. A user's MyDrive can't contain more than 100 levels of nested folders. Formore information, see Folder-depthlimit.

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

To fix this error:

1. Inform the user that Drive prevents placing folders more than100 levels deep.
2. If the user must create another nested folder, instruct them to reorganizethe intended parent folder to be fewer than 100 levels deep or use adifferent parent folder that already meets the requirement.

numChildrenInNonRootLimitExceeded

This error occurs when the limit for a folder's number of children (folders,files, and shortcuts) has been exceeded. There's a 500,000 item limit forfolders, files, and shortcuts directly in a folder. Items nested in subfoldersdon't count against this 500,000 item limit. For more information onDrive folder limits, refer to Folder limits inGoogle Drive.

The following JSON sample is a representation of this error:

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

To fix this error, try any of the following:

• Inform the user that Drive prevents folders with more than500,000 items.
• If the user must add more items to the full folder, instruct them toreorganize the folder to contain fewer than 500,000 items or use a similarfolder that already contains fewer items.

rateLimitExceeded

This error occurs when the project's rate limit has been reached. This limitvaries depending on the type of request. The following JSON sample is arepresentation of this error:

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

To fix this error, try any of the following:

• Raise the per-user quota in the Google Cloud project. For more information,request a quota increase.
• Batch requests to bundlemultiple API calls into one HTTP request.
• Use exponential backoff to retry therequest.

sharingRateLimitExceeded

This error occurs when the user reaches a sharing limit and is often linkedwith an email limit. The following JSON sample is a representation of thiserror:

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

To fix this error:

1. Don't send emails when sharing large amounts of files.
2. If one user is making numerous requests on behalf of many users of aGoogle Workspace account, consider a service account with domain-widedelegation using the quotaUserparameter.

storageQuotaExceeded

This error occurs when the user reaches their storage limit. The followingJSON sample is a representation of this error:

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

To fix this error:

1. Review your Drive account storage limits. For moreinformation, refer to Google Workspace storage and uploadlimits.

2. Manage files in your Google Drivestorage.

3. Buy more Googlestorage.

This error occurs when a user attempts to exceed the strict item limit on ashared drive. Each folder in a user's shared drive has a limit of 500,000 items,including files, folders, and shortcuts. This limit is based on item count, notstorage use. For more information, see Shared drive limits inGoogle Drive.

The following JSON sample is a representation of this error:

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

To fix this error, reduce the number of items in the shared drive. Shared driveswith too many files might be difficult to organize and search.

A teamDriveHierarchyTooDeep error occurs when the limit for the number ofshared drive nested folder levels has been exceeded. A user's shared drive can'tcontain more than 100 levels of nested folders. For more information, seeFolder-depth limit.

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

To fix this error:

1. Inform the user that shared drives prevents placing folders more than100 levels deep.
2. If the user must create another nested folder, instruct them to reorganizethe intended parent folder to be fewer than 100 levels deep or use adifferent parent folder that already meets the requirement.

This error occurs when a user attempts to access a shared drive in which they'renot a member. The following JSON sample is a representation of this error:

{ "error": { "errors": [ { "domain": "global", "reason": "teamDriveMembershipRequired", "message": "The attempted action requires shared drive membership." } ], "code": 403, "message": "The attempted action requires shared drive membership." }}

To fix this error, try any of the following:

1. Ask the manager of the shared drive to add you with the appropriatepermissions for the action you must perform.

2. Review Drive's Roles andpermissions to learn who can access and manageshared drives. Additional information about access levels can also be foundat Create a shareddrive.

This error occurs when a user attempts to move a folder from MyDrive into a shared drive. The following JSON sample is arepresentation of this error:

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

To fix this error, try any of the following:

• Move the individual items from the folder into a shared drive using theDrive API. Set the supportsAllDrives=true parameter to denote thesupport of both My Drive and shared drives.

• If you must move the folder into a shared drive, use theDrive UI. For more information, see Move folders into shareddrives as an admin.

This error occurs when a user attempts to add more than one parent to an item ina shared drive. The following JSON sample is a representation of this error:

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

To fix this error, use Drive shortcuts to add multiple links to afile. Although a shortcut can only have one parent, a shortcut file can becopied to the additional locations. For more information, see Create ashortcut to a Drive file.

UrlLeaseLimitExceeded

This error occurs when trying to save Google Play game data through yourapplication. The following JSON sample is a representation of this error:

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

To fix this error, complete or cancel any uploads for a snapshot before creatingmore.

userRateLimitExceeded

This error occurs when the per-user limit has been reached. This might be alimit from the Google Cloud console or a limit from the Drivebackend. The following JSON sample is a representation of this error:

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

To fix this error, try any of the following:

• Raise the per-user quota in the Google Cloud project. For more information,request a quota increase.

• If one user is making numerous requests on behalf of many users of aGoogle Workspace account, consider a service account with domain-widedelegation using the quotaUserparameter.

• Use exponential backoff to retry therequest.

For information about Drive API limits, refer to Usage limits.

404 errors

These errors mean that the requested resource isn't accessible or doesn't exist.

notFound

This error occurs when the user doesn't have read access to a file, or the filedoesn't exist. The following JSON sample is a representation of this error:

{ "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "File not found {fileId}" } ], "code": 404, "message": "File not found: {fileId}" }}

To fix this error:

1. If the file is located in a shared drive, and you're using thefiles.get method, make sure thesupportsAllDrives query parameter is set to true.
2. Inform the user that they don't have read access to the file or the filedoesn't exist.
3. Instruct the user to contact the file's owner and request permission to thefile.

429 errors

These errors mean that too many requests were sent to the API too quickly.

rateLimitExceeded

This error occurs when the user has sent too many requests in a givenamount of time. The following JSON sample is a representation of this error:

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

To fix this error, use exponentialbackoff to retry the request.

500, 502, 503, 504 errors

These errors occur when an unexpected server error arises while processing therequest. Various issues can cause these errors, including a request's timingoverlapping with another request or a request for an unsupported action, such asattempting to update permissions for a single page in Google Sites instead ofthe entire site.

The following is a list of 5xx errors:

• 500 Backend error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

To fix this error, use exponentialbackoff to retry the request.

• Improve performance
• Troubleshoot authentication and authorization issues