Throttling guidance | Graph API concepts

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see Microsoft Graph throttling guidance.

What is throttling?

Throttling limits the number of concurrent calls to a service to prevent overuse of resources. Azure Active Directory (AD) Graph is designed to handle a very high volume of requests. In the event of an overwhelming number of requests, throttling helps maintain optimal performance and reliability of the Azure AD Graph service.

Throttling limits vary based on the scenario. For example, if you are performing a large volume of writes to your tenant, the possibility for throttling is higher than if you are only performing reads.

What happens when throttling occurs?

When a throttling threshold is exceeded, Azure AD Graph limits any further requests from that client while the throttle is in effect. When throttled, Azure AD Graph returns HTTP status code 429 ("Too many requests"), and the requests fail. Throttling behavior can be dependent on the type and number of requests. For example, if you have a very high volume of requests, all requests types are throttled. Threshold limits vary based on the request type. Therefore, you could encounter a scenario where writes are throttled but reads are still permitted.

Common throttling scenarios

The most common causes of throttling of clients include:

• A large number of requests across all applications in a tenant.
• A large number of requests from a particular application across all tenants.

Best practices to handle throttling

• Reduce the number of operations per request.
• Reduce the frequency of calls.
• When requests fail with a HTTP error code 429, wait the number of seconds specified in the Retry-After response header field and retry the request.

When implementing error handling, use the HTTP error code 429 to detect throttling. The failed response will include the Retry-After field in the response header.

1. Wait the number of seconds specified in the Retry-After field.
2. Retry the request.
3. If the request fails again with a 429 error code, you are still being throttled, continue to use the recommended Retry-After delay and retry the request until it succeeds.

Backing off requests using the Retry-After delay is the fastest way to recover from throttling because AAD Graph continues to log resource usage while a client is being throttled. You should avoid immediate retries since all requests accrue against your usage limits.

For a broader discussion of throttling on the Microsoft Cloud, see Throttling Pattern.