Throttling guidance | Graph API concepts

  • Article

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

Important

Azure Active Directory (Azure AD) Graph is deprecated. Going forward, we will make no further investment in Azure AD Graph, and Azure AD Graph APIs have no SLA or maintenance commitment beyond security-related fixes. Investments in new features and functionalities will only be made in Microsoft Graph.

June 30, 2023 will mark the end of the three-year deprecation period for Azure AD Graph. Before June 30, 2023, existing applications using Azure AD Graph will not be impacted. After June 30, 2023, Azure AD Graph will enter its retirement phase where we will retire it in incremental steps to allow you sufficient time to migrate your applications to Microsoft Graph APIs. The first step in this plan, and at a later date that we will announce, we will block the creation of any new applications using Azure AD Graph.

For more details on the latest announcement, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.

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.