Resolve errors

The Google Drive API returns 2 levels of error information:

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

Drive apps should catch and handle all errors that might be encountered when using the REST API. This guide provides instructions on how to resolve specific API errors.

Resolve a 400 error: Bad request

This error can result 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.

Note: This list is not exhaustive, other cases can cause a 400 error.

Following is a sample JSON 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.

Resolve a 400 error: Invalid sharing request

This error can occur for several reasons. To determine the limit that has been exceeded, evaluate the reason field of the returned JSON. This error most commonly occurs because:

• Sharing succeeded, but the notification email was not correctly delivered.
• The Access Control List (ACL) change is not allowed for this user.

The message field indicates the actual error.

Sharing succeeded, but the notification email was not correctly delivered

Following is the JSON 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 [e-mail].\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

To fix this error, inform the user (sharer) they were unable to share because the notification email couldn't be sent to the email address they want to share with. The user should ensure they have the correct email address and that it can receive email.

The ACL change is not allowed for this user

Following is the JSON 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 sharing settings of the Google Workspace domain to which the file belongs. The settings might prohibit sharing outside of the domain or sharing a shared drive might not be permitted.

Resolve a 401 error: Invalid credentials

A 401 error indicates the access token that you're using is either expired or invalid. This error can also be caused by missing authorization for the requested scopes. Following is the JSON 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 API-specific authorization and authentication information.

Resolve a 403 error

An error 403 occurs when a usage limit has been exceeded or the user doesn't have the correct privileges. To determine the specific type of error, evaluate the reason field of the returned JSON. This error occurs for the following situations:

• The daily limit was exceeded.
• The user rate limit was exceeded.
• The project rate limit was exceeded.
• The sharing rate limit was exceeded.
• The user hasn't granted your app rights to a file.
• The user doesn't have sufficient permissions for a file.
• Your app can't be used within the signed in user's domain.
• Number of items in a folder was exceeded.

For information on Drive API limits, refer to Usage limits. For information on Drive folder limits, refer to Folder limits in Google Drive.

Resolve a 403 error: Daily limit exceeded

A dailyLimitExceeded error indicates the courtesy API limit for your project has been reached. Following is the JSON 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 cap usage of a particular resource. To fix this error, remove any usage caps for the "Queries per day" quota.

Resolve a 403 error: User rate limit exceeded

A userRateLimitExceeded error indicates the per-user limit has been reached. This might be a limit from the Google API Console or a limit from the Drive backend. Following is the JSON 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.

Note: Only request additional quota if your application exceeds the Drive API courtesy limit or the per-user limit. When exceeding the per-user limit, try to optimize your application code with batch requests to make fewer API calls.

• If one user is making numerous requests on behalf of many users of a Google Workspace account, consider a service account with domain-wide delegation using the quotaUser parameter.
• Use exponential backoff to retry the request.

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

Resolve a 403 error: Project rate limit exceeded

A rateLimitExceeded error indicates the project's rate limit has been reached. This limit varies depending on the type of requests. Following is the JSON representation 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 make fewer API calls.
• Use exponential backoff to retry the request.

Resolve a 403 error: Sharing rate limit exceeded

A sharingRateLimitExceeded error occurs when the user has reached a sharing limit. This error is often linked with an email limit. Following is the JSON representation of this error:

{
 "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. Do not send emails when sharing large amounts of files.
2. If one user is making numerous requests on behalf of many users of a Google Workspace account, consider a service account with domain-wide delegation using the quotaUser parameter.

Resolve a 403 error: Storage quota exceeded

A storageQuotaExceeded error occurs when the user has reached their storage limit. Following is the JSON 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 the storage limits for your Drive account. For more information, refer to Drive storage and upload limits

2. Free up space

   or get more storage from Google One.

Resolve a 403 error: The user has not granted the app {appId} {verb} access to the file {fileId}

An appNotAuthorizedToFile error occurs when your app is not on the ACL for the file. This error prevents the user from opening the file with your app. Following is the JSON 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 picker and prompt the user to open the file.
• Instruct the user to open the file using the Open with context menu in the Drive UI of your app.

You can also check the isAppAuthorized field on a file to verify that your app created or opened the file.

Resolve a 403 error: The user does not have sufficient permissions for file {fileId}

A insufficientFilePermissions error occurs when the user doesn't have write access to a file, and your app is attempting to modify the file. Following is the JSON representation 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 request edit access. You can also check user access levels in the metadata retrieved by files.get and display a read-only UI when permissions are missing.

Resolve a 403 error: App with id {appId} cannot be used within the authenticated user's domain

A domainPolicy error occurs when the policy for the user's domain doesn't allow access to Drive by your app. Following is the JSON representation of 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 the domain doesn't allow your app to access files in Drive.
2. Instruct the user to contact the domain Admin to request access for your app.

Resolve a 403 error: Number of items in folder was exceeded

A numChildrenInNonRootLimitExceeded 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 for folders, files, and shortcuts directly in a folder. Items nested in subfolders don't count against this 500,000 item limit. For more information on Drive folder limits, refer to Folder limits in Google Drive .

Resolve a 403 error: Number of items created by account was exceeded

An activeItemCreationLimitExceeded error occurs when the limit for the number of items, whether trashed or not, created by this account has been exceeded. All item types, including folders, count towards the limit.

Resolve a 404 error: File not found: {fileId}

The notFound error occurs when the user doesn't have read access to a file, or the file doesn't exist.

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

To fix this error:

1. Inform the user they don't have read access to the file or the file doesn't exist.
2. Instruct the user to contact the file's owner and request permission to the file.

Resolve a 429 error: Too many requests

A rateLimitExceeded error occurs when the user has sent too many requests in a given amount of time.

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

To fix this error, use exponential backoff to retry the request.

Resolve a 5xx error

A 5xx error occurs when an unexpected error arises while processing the request. This can be caused by various issues, including a request's timing overlapping with another request or a request for an unsupported action, such as attempting to update permissions for a single page in a Google Site instead of the site itself.

To fix this error, use exponential backoff to retry the request. Following is a list of 5xx errors:

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