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.

The rest of this page provides a reference of Drive errors, with some guidance on how to handle them in your app.

Handle error: revoked or invalid tokens

Google Drive apps should account for the API returning an HTTP 401 or HTTP 403 response when calling the Drive API. These errors could indicate any of:

  • Token expiry.
  • Token revocation. This would cause both the access token and the refresh token to stop working.
  • Token not authorized for needed scopes.
  • Request not authorized correctly with OAuth 2.0 protocol.

Token expiry can be handled by refreshing the credentials. If that call fails with an "Invalid Credentials" error, the issue is probably that the user has revoked access. For revoked access and all issues other than token expiry, the best remedy is to redirect the user through the OAuth dialog to re-grant access.

Handle API errors

Drive apps should catch and handle all errors that might be encountered when using the REST API. See Handling API Errors for a reference of the errors returned by the API.

Errors and suggested actions

In this section, you'll find the complete JSON representation of each listed error and a suggested actions you might take to handle it.

400: Bad request

User error. This can mean that a required field or parameter has not been provided, the value supplied is invalid, or the combination of provided fields is invalid.

This error can be thrown when trying to add a duplicate parent to a Drive item. It can also be thrown when trying to add a parent that would create a cycle in the directory graph.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "badRequest",
        "message": "Bad Request"
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

400: Invalid sharing request

An invalid sharing request can occur for several reasons. The following examples are common occurrences, not an exhaustive list of possible errors.

Sharing succeeded, but the notification email was not correctly delivered.

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

Suggested action: Check that both the sending and receiving users are not suspended, and able to send and receive emails.

The ACL change is not allowed for this user.

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

Suggested action: Check the sharing settings of the G Suite domain to which the file belongs.

401: Invalid credentials

Invalid authorization header. The access token you're using is either expired or invalid.

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

Suggested action: 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.

403: Daily limit exceeded

The Courtesy API limit for your project has been reached.

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

Suggested action: Request additional quota in the Google API Console under the Quotas tab of a project..

403: User rate limit exceeded

The per-user limit has been reached. This may be the limit from the Developer Console or a limit from the Drive backend.

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

Suggested actions:

  • Raise the per-user quota in the Developer Console project.
  • 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).
  • Use exponential backoff to retry the request.

403: Rate limit exceeded

The user has reached Google Drive API's maximum request rate. The limit varies depending on the kind of requests.

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

Suggested actions:

403: Sharing rate limit exceeded

The user has reached a sharing limit. This is often linked with an email limit.

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

Suggested actions:

  • Do not send emails when sharing lot of files.
  • 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).

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

The requesting app is not on the ACL for the file. The user never explicitly opened the file with this Drive app.

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

Suggested action: Open a picker and prompt the user to open the file, or direct the user to Drive to open the file with the app.

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

The user does not have write access to a file, and the app is attempting to modify that file.

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

Suggested action: Tell the user to request edit access to the file. You can also check user access levels in the metadata retrieved by files.get and display a read-only UI when permissions are missing.

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

The policy for the user's domain does not allow access to Google Drive by your app.

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

Suggested action: Tell the user that the domain doesn't allow your app to access files in Drive. Recommend they contact the domain admin to request access for your app.

404: File not found: {fileId}

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

Suggested action: Tell the user they don't have read access to the file or that the file doesn't exist. Recommend they ask the owner for permission to the file.

429: Too many requests

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

Suggested action: Use exponential backoff to retry the request.

500: Backend error

An unexpected error occurred while processing the request.

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

Suggested action: 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, called exponential backoff, improves bandwidth usage and maximizes throughput of requests in concurrent environments.

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.

傳送您對下列選項的寶貴意見...

這個網頁
Drive REST API
Drive REST API
需要協助嗎?請前往我們的支援網頁