Handling API 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.

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

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 suspendended, and able to send and receive emails.

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.

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:

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: Report to the user that there is a need to ask for those permissions in order to update the file. You may also want to check user access levels in the metadata retrieved by files.get and use that to change your UI to a read only UI.

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: Report to the user that the domain does not allow your app to access files in Drive. Suggest that the user 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: Report to users that they do not have read access to the file or that the file does not exist. Tell them that they should 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.

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, include a check before retrying non-idempotent requests.

Implementing exponential backoff

Exponential backoff is a standard error handling strategy for network applications in which the client periodically retries a failed request over an increasing amount of time. If a high volume of requests or heavy network traffic causes the server to return errors, exponential backoff may be a good strategy for handling those errors. Conversely, it is not a relevant strategy for dealing with errors unrelated to rate-limiting, network volume or response times, such as invalid authorization credentials or file not found errors.

Used properly, exponential backoff increases the efficiency of bandwidth usage, reduces the number of requests required to get a successful response, and maximizes the throughput of requests in concurrent environments.

Create requests are not idempotent. A simple retry is insufficient and may result in duplicate entities. Check whether the entity exists before retrying.

发送以下问题的反馈:

此网页
Drive REST API
Drive REST API