Directory API: Limits and Quotas

Limits and quotas protect the Google infrastructure from an automated process that uses the Directory API in an inappropriate way. Excessive requests from an API might result from a harmless typo, or may result from an inefficiently designed system that makes needless API calls. Regardless of the cause, blocking traffic from a specific source once it reaches a certain level is necessary for the overall health of the Google Workspace system. It ensures that one developer's actions cannot negatively impact the larger community.

In the unlikely event that your API request fails, the API returns an HTTP status code and reason for the error. Additionally, the body of the response contains a detailed description of what caused the error.

The following list shows the possible error codes, reasons, corresponding descriptions, and recommended action for errors caused by hitting quota limits.

Implementing Exponential Backoff

Exponential backoff is the process of a client periodically retrying a failed request over an increasing amount of time. It is a standard error handling strategy for network applications. Using exponential backoff increases the efficiency of bandwidth usage, reduces the number of requests required to get a successful response, and maximizes the throughput of requests in concurrent environments.

The flow for implementing simple exponential backoff is as follows.

1. Make a request to the API
2. Receive an error response that has a retry-able error code
3. Wait 1s + random_number_milliseconds seconds
4. Retry request
5. Receive an error response that has a retry-able error code
6. Wait 2s + random_number_milliseconds seconds
7. Retry request
8. Receive an error response that has a retry-able error code
9. Wait 4s + random_number_milliseconds seconds
10. Retry request
11. Receive an error response that has a retry-able error code
12. Wait 8s + random_number_milliseconds seconds
13. Retry request
14. Receive an error response that has a retry-able error code
15. Wait 16s + random_number_milliseconds seconds
16. Retry request
17. If you still get an error, stop and log the error.

In the above flow, random_number_milliseconds is a random number of milliseconds less than or equal to 1000. This is necessary to avoid certain lock errors in some concurrent implementations. random_number_milliseconds must be redefined after each wait.

Note: the wait is always (2 ^ n) + random_number_milliseconds , where n is a monotonically increasing integer initially defined as 0. n is incremented by 1 for each iteration (each request).

The algorithm is set to terminate when n is 5. This ceiling is in place only to stop clients from retrying infinitely, and results in a total delay of around 32 seconds before a request is deemed "an unrecoverable error". Your API client can implement a higher number of attempts if needed.

API Limits and Quotas