Resolve errors

The Drive API returns two 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.

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 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 email@domain.com.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

To fix this error, inform the user (sharer) that they were unable to share because the notification email couldn't be sent to the sharee. The user should ensure they have the correct email address and that the sharee 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 G Suite domain to which the file belongs. The sharing settings might be prohibiting sharing outside of the domain or sharing a shared drive might not be permitted.

Resolve a 401 error: Invalid credentials

A 401 error indicates that the access token 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 Authorizing Your App with Google Drive.

Resolve a 403 error: Usage limit exceeded

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 authenticated user's domain.

Resolve a 403 error: Daily limit exceeded

A dailyLimitExceeded error indicates that 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"
  }
}

To fix this error:

  1. Visit the Google API Console
  2. Select your project.
  3. Click the Quotas tab
  4. Request additional quota. For more information, see Request additional quota.

Resolve a 403 error: User rate limit exceeded

A userRateLimitExceeded error indicates that the per-user limit has been reached. This limit might be the limit from the 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:

  1. Raise the per-user quota in the Developer Console project. For more information, see Request additional quota.
  2. If one user is making a lot of requests on behalf of many users of a G Suite domain, consider a Service Account with authority delegation (setting the quotaUser parameter).
  3. Use exponential backoff to retry the request.

Resolve a 403 error: Rate limit exceeded

A rateLimitExceeded error indicates that the user has reached Google Drive API's maximum request rate. 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:

  1. Batch the requests.
  2. 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 lot of files.
  2. If one user is making a lot of requests on behalf of many users of a G Suite domain, consider a Service Account with authority delegation to impersonate the owner of each document to share (setting the quotaUser parameter).

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, perform one of the following operations:

You can also check the isAppAuthorized field on a file to see if the file was created by or opened with your app.

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

A insufficientFilePermissions error occurs when the user does not have write access to a file, and your app is attempting to modify that 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 Google 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 that 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 404 error: File not found: {fileId}

The notFound error occurs when the user does not have read access to a file, or the file does not 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 that the file doesn't exist.
  2. Instruct the user to ask the owner for 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 500 error: Backend error

A backendError occurs when an unexpected error arises while processing the request.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

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

Retry failed requests to resolve errors

You can periodically retry a failed request over an increasing amount of time to handle errors related to rate limits, network volume, or response time. For example, you might retry a failed request after one second, then after two seconds, and then after four seconds. This method is called exponential backoff and it is used to improve bandwidth usage and maximize throughput of requests in concurrent environments. When using exponential backoff, consider the following:

  • Start retry periods at least one second after the error.
  • If the attempted request introduces a change, such as a create request, add a check to make sure nothing is duplicated. Some errors, such as invalid authorization credentials or "file not found" errors, aren’t resolved by retrying the request.

Request additional quota

If you believe you need additional quota:

  1. Visit the Google API Console
  2. Select your project.
  3. Click the Quotas tab.
  4. Request additional quota.

Only request additional quota if your application exceeds the Drive API courtesy limit or the per-user limit. If exceeding the per-user limit, try to optimize your application code to make fewer requests.