Resolve errors  |  Gmail  |  Google for Developers (2024)

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 youdetermine how to handle the error.

Gmail apps should catch and handle all errors that might be encountered whenusing the REST API. This guide provides instructions on how to resolve specificAPI errors.

Resolve a 400 error: Bad request

This error might result from these errors yourcode:

• 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 expiredor invalid. This error can also be caused by missing authorization for therequested 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 refreshtoken. If you are using a client library, it automatically handles tokenrefresh. If this fails, direct the user through the OAuth flow, as describedin Authorizing your App with Gmail.

For additional information on Gmail limits, refer toUsage limits.

Resolve a 403 error: Usage limit exceeded

An error 403 occurs when a usage limit has been exceeded or the user doesn'thave the correct privileges. To determine the specific type of error, evaluatethe reason field of the returned JSON. This error occurs for the followingsituations:

• 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 toUsage limits.

Resolve a 403 error: Daily limit exceeded

A dailyLimitExceeded error indicates that the courtesy API limit for yourproject 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, seeRequest additional quota.

For additional information on Gmail limits, refer toUsage limits.

Resolve a 403 error: User rate limit exceeded

A userRateLimitExceeded error indicates that the per-user limit has beenreached. Following is theJSON 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 optimizeyour application code to make fewer requests or retry requests. For informationon retrying requests, refer toRetry failed requests to resolve errors.

For additional information on Gmail limits, refer toUsage limits.

Resolve a 403 error: Rate limit exceeded

A rateLimitExceeded error indicates that the user has reached Gmail API'smaximum 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 toUsage 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'tallow access to Gmail by your app. Following is the JSON representationof 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 concurrentrequest limit. Information about each limit follows. However, each limit can beresolved either by trying to retry failed requests or bysplitting processing across multiple Gmail accounts. Per-user limitscannot be increased for any reason. For more information about limits, seeUsage limits.

Mail sending limits

The Gmail API enforces the standard daily mail sending limits. These limitsdiffer for paying Google Workspace users and trialgmail.com users. For these limits, refer toGmail sending limits in Google Workspace.

These limits are per-user and are shared by all of the user's clients, whetherAPI clients, native/web clients or SMTP MSA. If these limits areexceeded, 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 formultiple 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 429error responses. So you cannot assume that a 200 response means the email wassuccessfully sent.

Bandwidth limits

The API has per-user upload and downloadbandwidth limits that areequal to, but independent of, IMAP. These limits are shared across all Gmail APIclients 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 errorsfor multiple hours before the request is accepted.

Concurrent Requests

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

Making many parallel requests for a single user or sending batches with alarge number of requests can trigger this error. A large number ofindependent API clients accessing the Gmail user mailbox simultaneously can alsotrigger 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 therequest.

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

To fix this error, retry failed requests. Following is alist 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 tohandle errors related to rate limits, network volume, or response time. Forexample, you might retry a failed request after one second, then after twoseconds, and then after four seconds. This method is calledexponential backoff and it is used to improve bandwidth usage and maximizethroughput 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 toyour 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 triggerrate limiting. Sending batches larger than 50 requests is not recommended. Forinformation on how to batch requests, refer toBatching requests.