Gmail API: Troubleshooting "User-rate limit exceeded" errors
Updated
by Gmelius
Google services (incl. Gmail) have limitations on how many data requests a third party application, such as Gmelius, and their users can make to it. This is also called rate-limiting and it is in place to ensure that an app's servers are not overwhelmed by too much traffic and maintain general good health.
Whenever an application interacts with a Gmail inbox, it uses one or more data requests on behalf of the signed in user. Gmail has a limit of how many data requests third-party platforms can make on behalf of all its users for a given time period. It also has limits on how many data requests each connection (i.e. single user) can make as well. So when this limit exceeds, it'll return an error code 429 "User-rate limit exceeded" when the platform attempts more data requests.
To address these errors, we recommend the following actions for Google Workspace administrators:
1. Review Third-party apps with access to Gmail
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.
A large number of independent API clients accessing the Gmail user mailbox simultaneously can lead to this error. Google Workspace Administrators should remove non-essential third-party apps accessing Gmail to reduce concurrent requests. This can be done from the Google Workspace Admin dashboard at Google Admin > Third-Party Apps.
2. Disable IMAP/POP
The Gmail 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 hit in 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.
Mail clients pinging Gmail through IMAP and POP are often the cause for this error. You can check whether IMAP/POP is enabled for your Google Workspace domain by going to Google Admin > Apps > Gmail.
As enabling IMAP/POP can represent a data loss risk for your company, we recommend disabling it for your whole domain. If this is not feasible, then disable IMAP/POP for the impacted users of your domain by creating a corresponding Group or Organizational Unit.
3. Contact Google Support
If errors continue after implementing these measures, or if they are not applicable, contact Google Support by going to admin.google.com and clicking on "Support". Their team can help identify the issue and provide solutions to avoid "User-rate limit exceeded" errors.
By taking these steps, administrators can help prevent data request overloads and maintain efficient Gmail API interactions.
