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.

Code	Reason	Description	Recommended Action
403	userRateLimitExceeded	Indicates that the user rate limit has been exceeded. The default value set in the Google Cloud console is 2,400 queries per minute per user per Google Cloud project.	Increase the per user limits from the Admin SDK API Quotas page of your Google Cloud project, or slow down the rate at which you are sending the requests using exponential backoff.
403	quotaExceeded	Indicates that the limit of concurrent requests for a certain operation has been reached.	Retry using exponential back-off. You need to slow down the rate at which you are sending the requests.
429	rateLimitExceeded	Indicates that the limit of concurrent requests for a certain operation has been reached.	Retry using exponential back-off. You must slow down the rate at which you are sending the requests. This limit is per Google Workspace account, not per API client or per user. This limit can't be increased.

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.

Make a request to the API
Receive an error response that has a retry-able error code
Wait 1s + random_number_milliseconds seconds
Retry request
Receive an error response that has a retry-able error code
Wait 2s + random_number_milliseconds seconds
Retry request
Receive an error response that has a retry-able error code
Wait 4s + random_number_milliseconds seconds
Retry request
Receive an error response that has a retry-able error code
Wait 8s + random_number_milliseconds seconds
Retry request
Receive an error response that has a retry-able error code
Wait 16s + random_number_milliseconds seconds
Retry request
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

API Limit Categories	Limits
Creating users	You cannot create more than 10 users per domain per second using the Directory API.
Group added as member to another group	May have a delay up to 10 minutes before the child group's members appear as members of the parent group. This limit could change depending on the system's capacity.
Mobile devices	Using the Directory API, you can perform up to: 20 action requests per second. 20 delete requests per second. 10 get requests per second. 10 list requests per second.
Renaming users	Can take up to 10 minutes to propagate across all services. Before renaming a user, it is recommended to log out the user from all browser sessions and services. For more details, see Update users.
Creating/updating Organizational Units	You cannot create/update more than 1 organizational unit per customer per second using the Directory API. The customer's organizational unit hierarchy is limited to 35 levels of depth. The total number of organizational units per customer must not exceed 40,000.
API Quota Categories	Quotas
Chrome devices `annotatedLocation`, max characters	The maximum number of characters for a device's location information is 200.
Chrome devices `notes`, max characters	The maximum number of characters for a device's notes information is 500.
Chrome devices, `user` maximum characters	The maximum number of characters for a device user's name is 100.
Domain aliases, maximum	The maximum number of domain aliases is 20.
Groups, description	The maximum number of characters in a description is 4,096.
Groups, per account	With a G Suite Legacy Free Edition account, the number of groups is limited to 10. Other editions have no limit to the number of groups.
Groups, members per group	With a G Suite Legacy Free Edition account, a group can contain up to 100 members. Other editions have no limit to the number of members a group can have. For group membership limits per user, see Understand Groups policies and limits
maxResults query string	The API returns: Chrome and mobile devices – A default and a maximum of 100 entries per page. Groups and group members – A default and maximum of 200 entries per page. Users – A default of 100 entries and a maximum of 500 entries per page. The user alias and organizational unit resources do not use response pagination. All user primary emails are returned in alphabetical order and the response order is case insensitive.
Multiple domain, maximum number of domains allowed in an account	600 (1 primary domain + 599 additional domains)
Organizational Unit, maximum number of users moved at one time	20 users can be moved at one time. And the user's primary email addresses must already exist in the account.
User aliases	The total number of aliases allowed for every user account is 30.
User aliases, using a deleted alias	A deleted user alias can be used again immediately.

Other Types of Limits	Limitations and Guidelines
Billing and creating users	For users on a flexible plan for Google Workspace, creating users using this API will have monetary impact, and will result in charges to your customer billing account. For instance, if you are on a flexible plan for Google Workspace, creating 10 users will result in charges for 10 Google Workspace licenses being posted to your account, prorated from the time the creation is done. If you are on an annual plan, you would already have committed to paying for a certain number of licenses upfront, and you can only create as many users as per your commitment. For more information about billing plans and your billing account, see the administration help center.
First and Last Names	First and last names have a maximum of 40 characters. They support Unicode/UTF-8 characters, and can contain spaces, letters (a-z), numbers (0-9), dashes (-), forward slashes (/), and periods (.). For more information about character usage rules, see the administration help center.
Groups, deleting	Deleting a group does not delete the group member's user accounts.
Groups and group members, email address change	In this version of the API, a group's email address can be changed before the Google Workspace service is enabled. Use the Admin console to change a group member's email address. Once changed, the API automatically reflects the email address changes.
Groups, settings	Groups access settings, sharing options, monitoring, and discussion archive is managed using the Admin console. For more information about groups settings, see the administration help center.
Groups, sending messages	To deter spam and email abuse, Google limits the number of messages you can send at once to external recipients. If you send a message to a group, each external member is counted as one recipient. For more information, see Email sending limits and Prevent mail to Gmail users from being blocked or sent to spam .
Groups, sending NDR messages	You cannot send or forward non-delivery receipts (NDRs), also called "bounce messages", to a group.
Groups created by users, limitations	For user-created group limits, see the administration help center
Organizational Unit, turning services on/off	Use the Admin console to manage turning services on and off for an organizational unit.
Passwords	Can contain any combination of characters. A minimum of 8 characters is required. The maximum length is 100 characters.
Photos	In this version of the API, a photo is the user's latest Google profile photo.
User names	User names can contain letters (a-z), numbers (0-9), dashes (-), underscores (_), and Google Workspace recognizes dots or periods (.). This is not the same as Gmail. A user name may not contain an equal sign (=), brackets (<,>), or more than one period (.) in a row. For more information, see the administration help center.
User names, renaming	Google Hangouts discards all remembered chat invitations after renaming. The user must request permission to chat with friends again. The old user name is retained as an email alias to ensure continuous mail delivery in the case of email forwarding settings and will not be available as a new user name. For important details on the impact of renaming users, see the administration help center. Use the Delete a user's alias operation to remove the email alias after renaming.
Users in multiple domains	A Google Workspace account can include any of your domains. In a multiple domain account, users in one domain can share services with users in other account domains. Multiple domain components are: Primary domain -- Your account's primary domain is the domain of the administrator who accepted the Google Workspace Terms of Service agreement. This domain is at the account-level in the top-level organizational unit. When signing up for a Google Workspace account, we recommend using your business domain for the primary domain, and reserve your other domains for specialized uses such as pilots and testing. All super administrators can manage the full account. The API cannot change or move the Google Workspace account's primary domain. However, the API can rename a user's account, changing its email address from one domain to another. For Google Workspace accounts, you have 21 days to verify your ownership of the primary domain. For additional domains, you must verify your domain ownership before using the domain for a user's primary email address. In these cases, the 21 day grace period does not apply. In this version of the API, the primary domain's settings apply to all domains associated with the account except for the user access to the Google Workspace services. Additional account domains -- After establishing your primary domain and setting up your account, your can add your additional domains to the account. For additional domains, verify your ownership when setting up this domain and before using the domain for a user's primary email address. User's home domain -- The domain used in a user's primary email address is the user's home domain. This domain can be any domain in the account, including the primary domain. For the latest multiple domain limitations, see multiple domain limitations. This includes information for domain aliases, account merging, etc.
Warnings, group members	GROUP_CANNOT_CONTAIN_CYCLE – The API does not allow a cycle in group memberships. For example, if group1 is a member of group2, group2 cannot be a member of group1.