Resolve errors

The Gmail 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.

Your Gmail app should catch and handle all errors you encounter when using the REST API. This guide provides instructions on how to resolve specific Gmail API errors.

HTTP status code summary

Error code	Description
`200 - OK`	The request is successful (this is the standard response for successful HTTP requests).
`400 - Bad Request`	The server couldn't fulfill the request due to a client error.
`401 - Unauthorized`	The request contains invalid credentials.
`403 - Forbidden`	The server received and understood the request, but the user doesn't have permission to perform the request.
`404 - Not Found`	The requested resource couldn't be found.
`429 - Too Many Requests`	Too many requests to the API.
`500, 502, 503, 504 - Server Errors`	An unexpected error occurred while processing the request.

400 errors

These errors mean that the request has an error, often due to a missing required parameter.

`badRequest`

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

A required field or parameter is missing.
A supplied value or combination of fields is invalid.
The attachment is invalid.

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.

401 errors

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

`authError`

This error occurs when the access token you're using is either expired or invalid. Missing authorization for the requested scopes can also cause this error. 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 you're using a client library, it automatically handles token refresh. If this fails, direct the user through the OAuth flow, as described in Learn about authentication and authorization.

For additional information on Gmail limits, see Usage limits.

403 errors

These errors occur when you exceed a usage limit or the user doesn't have the correct privileges. To determine the cause, evaluate the reason field of the returned JSON. This error occurs in the following situations:

Your app can't be used within the authenticated user's domain.
The project exceeded the daily limit.
The user exceeded the rate limit.
The project exceeded the rate limit.

For more information, see Usage limits.

`dailyLimitExceeded`

This error occurs when your project reaches its API limit. The following JSON 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 occurs when the application owner sets a quota limit to cap usage of a particular resource. To fix this error, raise the quota in the Google Cloud project. For more information, see Manage quota limits.

`domainPolicy`

This error occurs when the policy for the user's domain doesn't allow your app to access Gmail. The following JSON is the representation of this error:

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

To fix this error, try the following:

Inform the user that the domain doesn't allow your app to access Gmail.
Instruct the user to contact their domain administrator to request access for your app.

`rateLimitExceeded`

This error indicates that the user has reached the maximum request rate for the Gmail API. This limit varies depending on the request type. The following JSON sample is a 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 the following:

Request a quota increase.
Use exponential backoff to retry the request.

`userRateLimitExceeded`

This error occurs when a request reaches the per-user limit. 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 to optimize your application code to make fewer requests or use exponential backoff to retry the request.

429 errors

A 429 "Too many requests" error can occur due to daily per-user limits (including mail sending limits), bandwidth limits, or a per-user concurrent request limit. Information about each limit follows. However, each limit can be resolved either by retrying failed requests or by splitting processing across multiple Gmail accounts.

You can't increase per-user limits. For more information about limits, see Usage limits.

Mail sending limits

The Gmail API enforces the standard daily mail sending limits. These limits differ for paying Google Workspace users and trial gmail.com users. For these limits, refer to Gmail sending limits in Google Workspace.

These limits are per-user and are shared by all of the user's clients, whether API clients, built-in or web clients, or SMTP MSA. If you exceed these limits, the API returns an HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" error with a retry time. Exceeding daily limits might result in these errors for multiple hours before the server accepts the request.

The mail sending pipeline is complex: once the user exceeds their quota, there can be a delay of several minutes before the API begins returning 429 error responses. You can't assume that a 200 response means the email was successfully sent.

Bandwidth limits

The API has per-user upload and download bandwidth limits that are equal to, but independent of, IMAP. These limits are shared across all Gmail API clients for a user.

Users typically only encounter these limits in exceptional or abusive situations. If you exceed these limits, the API returns an HTTP 429 "Too many requests: User-rate limit exceeded" error with a retry time. Exceeding daily limits might result in these errors for multiple hours before the server accepts the request.

Concurrent requests

The Gmail API enforces a per-user concurrent request limit (in addition to the per-user rate limit). This limit is shared by all Gmail API clients accessing a user and ensures that no API client is overloading a Gmail user mailbox or their backend server.

Making many parallel requests for a single user or sending batches with a large number of requests can trigger this error. A large number of independent API clients accessing the Gmail user mailbox simultaneously can also trigger this error. If you exceed this limit, the API returns an HTTP 429 "Too many requests: Too many concurrent requests for user" error.

500, 502, 503, 504 errors

These errors occur when an unexpected server error arises while processing the request. Various issues can cause these errors, 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 Google Sites instead of the entire site.

The following is a list of 5xx errors:

500 Backend error
502 Bad gateway
503 Service unavailable
504 Gateway timeout

`backendError`

This error occurs when an unexpected error arises while processing the request. The following JSON sample is a representation of this error:

{
  "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's used to improve bandwidth usage and maximize throughput of requests in concurrent environments.

Start retry periods at least one second after the error.

Manage quota limits

To view or change usage limits for your project, or to request an increase to your quota, do the following:

If you don't already have a billing account for your project, then create one.
Visit the Enabled APIs page of the API library in the API Console, and select an API from the list.
To view and change quota-related settings, select Quotas. To view usage statistics, select Usage.

For more information, see View and manage quotas.

Batch requests

Batch requests can improve performance, but larger batch sizes can trigger rate limiting. Don't send batches larger than 50 requests. For information on how to batch requests, refer to Batch requests.