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.

Gmail 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 might result from these errors your code:

  • A required field or parameter hasn't been provided.
  • The value supplied or a combination of provided fields is invalid.
  • Invalid attachment.

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 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 you are using a client library, it automatically handles token refresh. If this fails, direct the user through the OAuth flow, as described in Authorizing your App with Gmail.

For additional information on Gmail limits, refer to Usage limits.

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.
  • Your app can't be used within the authenticated user's domain.

For additional information on Gmail limits, refer to Usage limits.

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.

For additional information on Gmail limits, refer to Usage limits.

Resolve a 403 error: User rate limit exceeded

A userRateLimitExceeded error indicates that the per-user limit has been reached. 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 to optimize your application code to make fewer requests or retry requests. For information on retrying requests, refer to Retry failed requests to resolve errors.

For additional information on Gmail limits, refer to Usage limits.

Resolve a 403 error: Rate limit exceeded

A rateLimitExceeded error indicates that the user has reached Gmail 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, retry failed requests.

For additional information on Gmail limits, refer to Usage limits.

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 Gmail by your app. Following is the JSON 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:

  1. Inform the user that the domain doesn't allow your app to access Gmail.
  2. Instruct the user to contact the domain Admin to request access for your app.

Resolve a 429 error: Too many requests

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 trying to retry failed requests or by splitting processing across multiple Gmail accounts. Per-user limits cannot be increased for any reason. 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, native/web clients or SMTP MSA. If these limits are exceeded, a HTTP 429 Too Many Requests "User-rate limit exceeded" "(Mail sending)" error is returned with time to retry. Note that daily limits being exceeded may result in these types of errors for multiple hours before the request is accepted.

The mail sending pipeline is complex: once the user exceeds their quota, there can be a delay of several minutes before the API begins to return 429 error responses. So you cannot 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 given user.

These limits are typically only hit in exceptional or abusive situations. If these limits are exceeded a HTTP 429 Too Many Requests "User-rate limit exceeded" error is returned with a time to retry. Note that daily limits being exceeded may result in these types of errors for multiple hours before the request is accepted.

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 given 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 this limit is exceeded a HTTP 429 Too Many Requests "Too many concurrent requests for user" error is returned.

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, retry failed requests. Following is a list of 500 errors:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

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.

Start retry periods at least one second after the error.

View or change usage limits, increase quota

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

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

Batch requests

Using batching is encouraged, however, larger batch sizes are likely to trigger rate limiting. Sending batches larger than 50 requests is not recommended. For information on how to batch requests, refer to Batching requests.