Manage quotas

As the Calendar API is a shared service, we enforce quotas to make sure that it's used fairly by all users. If you perform a lot of writes in quick succession, you may be rate-limited—see the general Calendar usage limits for more information. In addition, there are two relevant quotas for Calendar API:

  • Per minute per project: This is the number of requests made by your entire project. This can be increased if your project has a lot of users.
  • Per minute per project per user: This is the number of requests made by your project by any one particular user (the user or service account performing the request, not necessarily the user who owns the calendar being accessed). This typically cannot be increased, so it's important to ensure that you use the API efficiently.

If either quota is exceeded, you will be rate limited and receive a 403 "usageLimits" response or a 429 response to your queries. If this happens, you should use an exponential back off and try again later. In addition, you might be rate limited at any time for operational reasons, but typically this is very rare. Provided your project stays within these quotas, there is no limit to the number of requests you can make per day.

Quotas are calculated per minute using a sliding window, so a rapid burst of traffic which exceeds your per-minute quota during one minute will result in rate limiting during the next window to ensure that, on average, your usage remains within the limits.

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.

Use exponential backoff

When we want you to slow down your rate of requests, we will return a 403 "usageLimits" response or a 429 response (see the full error documentation). This is not a fatal error and we expect you to retry the request after a short interval. If requests are still arriving too quickly, we will ask again, and so on. For this to work correctly, it is important that the delays between requests increase over time.

Generally, you should use truncated exponential backoff; the Google Cloud Storage documentation has a good explanation of how this works and the preferred algorithm. If you're using a Google client library, this will normally be handled for you; consult your library documentation. Normally, you should use the library implementation rather than write your own.

Randomize traffic patterns

Calendar clients are prone to spiky traffic patterns caused by multiple clients performing operations at the same time. For example, a common anti-pattern is for a Calendar client to perform a full sync at midnight. This is almost guaranteed to exceed your per-minute quota, resulting in rate limiting and backoffs.

To avoid this, make sure that your traffic is spread throughout the day wherever possible. If your client needs to do a daily sync, have the client determine a random time (different for each client). If you need to perform an operation on a regular basis, vary the interval +/- 25%. This will distribute the traffic more evenly and provide a much better user experience.

Use push notifications

A common use case is to want to perform an action whenever something changes in the user's calendar. An anti-pattern here is to repeatedly poll every calendar of interest. This will very quickly use up all your quota—for example, if your application has 5,000 users and polls each user's calendar once a minute, then this will require a per-minute quota of at least 5,000 even before any work is done.

Server-side applications can register for push notifications, which allows us to notify you when something of interest happens. These require more work to set up, but allow for dramatically more efficient use of your quota, and provide a better user experience. For more information, see Push notifications.

Proper accounting with service accounts

If your application is performing requests using domain-wide delegation, by default the service account is charged with regard to "per minute per project per user" quotas, and not the user you're impersonating. This means that the service account will likely run out of quota and be rate-limited, even though it might be operating on multiple users' calendars. You can avoid this by using the quotaUser URL parameter (or x-goog-quota-user HTTP header) to indicate which user will be charged. This is used only for quota calculations. See Limiting requests per user in the Cloud documentation for more information.