Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update to sharepoint throttling page #10157

Merged
merged 11 commits into from
Mar 24, 2025
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Avoid getting throttled or blocked in SharePoint Online
description: Learn about throttling in SharePoint Online and learn how to avoid being throttled or blocked.
ms.date: 07/26/2024
ms.date: 03/17/2025
ms.assetid: 33ed8106-d850-42b1-8d7f-5ba83901149c
ms.localizationpriority: high
---
@@ -32,18 +32,65 @@ For requests that a user performs directly in the browser, SharePoint Online red
For requests that an application makes, including [Microsoft Graph](/graph), CSOM, or REST calls, SharePoint Online returns HTTP status code 429 ("Too many requests") or 503 ("Server Too Busy") and the requests will fail.

- HTTP 429 indicates the calling application sent too many requests in a time window and exceeded a predetermined limit.
- HTTP 503 indicates the service isn't ready to handle the request. The common cause is that the service is experiencing more temporary load spikes than expected.
- HTTP 503 indicates the service isn't ready to handle the request. The common cause is that the service is experiencing more temporary load spikes.

In both cases, a `Retry-After` header is included in the response indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` may result in more throttling.

If the offending application continues to exceed usage limits, SharePoint Online may completely block the application or specific request patterns from the application; in this case, the application will keep getting HTTP status code 503, and Microsoft will notify the tenant of the block in the Office 365 Message Center.

### Resource units

Some limits are measured in terms of API costs, [Microsoft Graph APIs](/graph) have a predetermined resource unit cost per request:

| Resource units per request | Operations |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| 1 | <li>Single item query, such as get item <li>Delta with a token <li>Download file from drive item |
| 2 | <li>Multi item query, such as list children, except delta with a token <li>Create, update, delete and upload |
| 5 | <li>All permission resource operations, including `$expand=permissions` |

> [!NOTE]
> We reserve the right to change the API resource unit cost.
### User Throttling

Throttling limits the number of calls and operations collectively made by applications on behalf of a user to prevent the overuse of resources.

That said, it's rare for a user to get throttled in SharePoint Online. The service is robust, and it's designed to handle high volume. If you do get throttled, 99% of the time it is because of custom code, such as custom web parts, complex list view and queries, or custom apps users run. That doesn’t mean that there aren’t other ways to get throttled, just that they’re less common. For example, one user syncing a large amount of data across 10 machines at the same time could trigger throttling.

| Category | Type of throttling | Time interval | Limit |
|--------------|------------------------------|-------------------|-----------|
| User | RPS | 5 min | 3,000 |
| User | Ingress | 1 H | 50 GB |
| User | Egress | 1 H | 100 GB |
| User | Delegation Token Request | 5 min | 50 |
| User | External sharing emails | 1 H | 200 |

> [!NOTE]
> Displayed limits are default values. Microsoft may change these limits at any time. Your experience may vary
### Tenant Throttling

Some throttling limits are applied at the Tenant level to ensure the operations collectively made do not overuse resources.

When a customer enables Multi-Geo, each geo gets its own limits (usage measurement not shared across geos). For the limits that are dependent on license count, the total tenant user license counts is used (total users across all geos).

| Category | Type of throttling | Time interval | Tenant license count | Limit |
|--------------|--------------------------------------|-------------------|--------------------------|-----------|
| Tenant | [Resources Units](#resource-units) | 5 min | 0 - 1,000 | 18,750 |
| Tenant | [Resources Units](#resource-units) | 5 min | 1,001 - 5,000 | 37,500 |
| Tenant | [Resources Units](#resource-units) | 5 min | 5,001 - 15,000 | 56,250 |
| Tenant | [Resources Units](#resource-units) | 5 min | 15,001 - 50,000 | 75,000 |
| Tenant | [Resources Units](#resource-units) | 5 min | 50,000+ | 93,750 |
| Tenant | Assign Sensitivity Label | 5 min | no license bound | 100 |
| Tenant | PeopleManagerAPIs | 5 min | 0 - 1,000 | 3,000 |
| Tenant | PeopleManagerAPIs | 5 min | 1,001 - 5,000 | 6,000 |
| Tenant | PeopleManagerAPIs | 5 min | 5,001 - 15,000 | 9,000 |
| Tenant | PeopleManagerAPIs | 5 min | 15,001 - 50,000 | 12,000 |
| Tenant | PeopleManagerAPIs | 5 min | 50,000+ | 15,000 |

> [!NOTE]
> Displayed limits are default values. Microsoft may change these limits at any time. Your experience may vary
### Application Throttling

In addition to throttling by user account, limits are also applied to applications in a tenant.
@@ -52,42 +99,42 @@ Every application has its own limits in a tenant, which are based on the number

SharePoint provides various APIs. Different APIs have different costs depending on the complexity of the API. The cost of APIs is normalized by SharePoint and expressed by resource units. Application’s limits are also defined using resource units.

The table below defines the resource unit limits for an application in a tenant:

| License count | 0 – 1k | 1k – 5k | 5k - 15k | 15k - 50k | 50k+ |
| --------------- | --------- | --------- | --------- | --------- | --------- |
| App 1 minute | 1,200 | 2,400 | 3,600 | 4,800 | 6,000 |
| App daily | 1,200,000 | 2,400,000 | 3,600,000 | 4,800,000 | 6,000,000 |

> [!NOTE]
> Microsoft reserves the right to change the resource unit limits.
For multitenant applications:

1. Each tenant hosting the application is considered distinct, operating independently from others. Consequently, every application is subject to its own usage limits within each tenant as defined above.
1. The consumption of resource units by the application is to be measured on a per-tenant, per-application basis. This ensures that each tenant-application pair remains within the permissible resource limits specified for that particular tenant.
1. Should the application reach its resource limit within one tenant, this occurrence will not affect other instances of the application operating in different tenants. Each tenant's resource utilization is isolated, preventing cross-tenant impact.

In terms of API costs, [Microsoft Graph APIs](/graph) have a predetermined resource unit cost per request:

| Resource units per request | Operations |
| -------------------------- | ------------------------------------------------------- |
| 1 | <li>Single item query, such as get item <li>Delta with a token <li>Download file from drive item |
| 2 | <li>Multi item query, such as list children, except delta with a token <li>Create, update, delete and upload |
| 5 | <li>All permission resource operations, including $expand=permissions |

> [!NOTE]
> We reserve the right to change the API resource unit cost.
Delta with a token is the most efficient way to scan content in SharePoint, and we talk more in detail at the [best practices for scanning applications](https://aka.ms/ScanGuidance). To help applications that follow the guidance, we lower the resource unit cost of delta requests with a token to 1 resource unit, although it's a multi-item query. The delta request without a token is considered a multi-item query and costs 2 resource units per request.

In [batching](/graph/json-batching), requests in a batch are evaluated individually by resource units.

CSOM and REST don't have a predetermined resource unit cost and they usually consume more resource units than [Microsoft Graph APIs](/graph) to achieve the same functionality. In addition to resource unit limits, CSOM and REST are also subject to other internal resource limits, so if applications call CSOM and REST, they may experience more throttling than the limits described in this document. We highly recommend you choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible.

Since application limits are in resource units, the actual request rate, such as requests per minute, depends on the application’s API choice and the corresponding API resource unit cost. In general, you can estimate the request rate using an average of 2 resource units per request and divide resource unit limits by 2 to get the estimated request rate.

Although each application has its limits within a tenant and we allow tenants to run more than one application, multiple applications running against the same tenant share the same resource bucket, and in rare occurrences can cause rate limiting when too many applications send requests at the time.
| Category | Type of throttling | Time interval | Tenant license count | Limit |
|--------------------|--------------------------------------|-------------------|--------------------------|------------|
| Per APP Per Tenant | [Resources Units](#resource-units) | 24 H | 0 - 1,000 | 1,200,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 24 H | 1,001 - 5,000 | 2,400,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 24 H | 5,001 - 15,000 | 3,600,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 24 H | 15,001 - 50,000 | 4,800,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 24 H | 50,000+ | 6,000,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 1 min | 0 - 1,000 | 1,250 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 1 min | 1,001 - 5,000 | 2,500 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 1 min | 5,001 - 15,000 | 3,750 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 1 min | 15,001 - 50,000 | 5,000 |
| Per APP Per Tenant | [Resources Units](#resource-units) | 1 min | 50,000+ | 6,250 |
| Per APP Per Tenant | Ingress | 1 H | no license bound | 400 GB |
| Per APP Per Tenant | Egress | 1 H | no license bound | 400 GB |
| Per APP Per Tenant | Specific Sharing APIs | 5 min | no license bound | 300 |

> [!NOTE]
> Displayed limits are default values. Microsoft may change these limits at any time. Your experience may vary
### Other Limits

| Category | Type of throttling | Time interval | Limit |
|-------------------------------|--------------------------------------|-------------------|-----------|
| SharePoint Embedded containers| [Resources Units](#resource-units) | 1 min | 3,000 |
| Per Site | Anonymous Link | 5 min | 3,000 |
| Per Site | Anonymous Egress (Download) | 2 H | 100 GB |
| Per Site | External sharing emails | 1 H | 200 |

> [!NOTE]
> Displayed limits are default values. Microsoft may change these limits at any time. Your experience may vary
## How to handle throttling?

@@ -98,11 +145,22 @@ Below is a quick summary of the best practices to handle throttling:
- Choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible
- Use the `Retry-After` and `RateLimit` HTTP headers
- Decorate your traffic so we know who you are (see section on traffic decoration best practice more on that below)
- Consider using [Graph Data Connect for Sharepoint](https://techcommunity.microsoft.com/blog/microsoft_graph_data_connect_for_sharepo/links-about-microsoft-graph-data-connect-for-sharepoint/4069045) for broad sites analytics

As stated earlier, [Microsoft Graph](/graph) is cloud born APIs that have the latest improvements and optimizations. In general, [Microsoft Graph](/graph) consumes less resources than CSOM and REST to achieve the same functionality. Hence, adopting [Microsoft Graph](/graph) can improve the application's performance and reduce throttling.
As stated earlier, [Microsoft Graph](/graph) is cloud born APIs that have the latest improvements and optimizations. In general, [Microsoft Graph](/graph) consumes fewer resources than CSOM and REST to achieve the same functionality. Hence, adopting [Microsoft Graph](/graph) can improve the application's performance and reduce throttling.

If you do run into throttling, we require using the `Retry-After` HTTP header to ensure minimum delay until the throttle is removed. The `RateLimit` HTTP headers send you early signals when you're close to limits and you can proactively reduce requests to avoid hitting the throttle.

Delta with a token is the most efficient way to scan content in SharePoint, and we talk more in detail at the [best practices for scanning applications](https://aka.ms/ScanGuidance). To help applications that follow the guidance, we lower the resource unit cost of delta requests with a token to 1 resource unit, although it's a multi-item query. The delta request without a token is considered a multi-item query and costs 2 resource units per request.

In [batching](/graph/json-batching), requests in a batch are evaluated individually by resource units.

CSOM and REST don't have a predetermined resource unit cost and they usually consume more resource units than [Microsoft Graph APIs](/graph) to achieve the same functionality. In addition to resource unit limits, CSOM and REST are also subject to other internal resource limits, so if applications call CSOM and REST, they may experience more throttling than the limits described in this document. We highly recommend you choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible.

Since application limits are in resource units, the actual request rate, such as requests per minute, depends on the application’s API choice and the corresponding API resource unit cost. In general, you can estimate the request rate using an average of 2 resource units per request and divide resource unit limits by 2 to get the estimated request rate.

Although each application has its limits within a tenant and we allow tenants to run more than one application, multiple applications running against the same tenant share the same resource bucket, and in rare occurrences can cause rate limiting when too many applications send requests at the time.

### Retry-after header

When applications experience throttling, SharePoint Online returns a `Retry-After` HTTP header in the request indicating how long in seconds the calling application should wait before retrying or making a new request.
@@ -126,33 +184,37 @@ The `RateLimit` headers are returned on a **best-efforts** basis, so application
Below is the list of limits that we support the `RateLimit` headers for. The policies and values are subject to change:

| limit | Condition | limit value | Description |
| -------------------------- | ------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
|----------------------------|---------------------------|---------------|------------------------------------------------------------------------------------------------------------------|
| App 1-minute resource unit | Usage >= 80% of the limit | Resource unit | When an application consumes 80% or more of its app 1-minute limit, the limit, remaining, and reset are returned.|

Below are some examples to help you understand the `RateLimit` headers:

- An application has consumed 90% of its resource unit quota (1,080 out of 1,200), and its consumption is within all the limits that apply to it. The request succeeds and the `RateLimit` headers are returned.
```
HTTP/1.1 200 Ok
RateLimit-Limit: 1200
RateLimit-Remaining: 120
RateLimit-Reset: 5
```

```
HTTP/1.1 200 Ok
RateLimit-Limit: 1200
RateLimit-Remaining: 120
RateLimit-Reset: 5
```
- An application has consumed 100% of its resource unit quota, so it gets throttled due to this policy. The request is throttled and the `RateLimit` headers are returned. The `Retry-After` matches the `RateLimit-Reset`.
```
HTTP/1.1 429 Too Many Requests
Retry-After: 31
RateLimit-Limit: 1200
RateLimit-Remaining: 0
RateLimit-Reset: 31
```
```
HTTP/1.1 429 Too Many Requests
Retry-After: 31
RateLimit-Limit: 1200
RateLimit-Remaining: 0
RateLimit-Reset: 31
```
- An application has consumed 90% of its resource unit quota but its consumption has already reached other limits that the `RateLimit` headers don't support. In this case, the request is throttled and the `RateLimit` headers aren't returned to avoid confusion although the condition to return the headers is satisfied.
```
HTTP/1.1 429 Too Many Requests
Retry-After: 9
```
```
HTTP/1.1 429 Too Many Requests
Retry-After: 9
```
Additional information can be found in [Prevent throttling in your application by using RateLimit headers in SharePoint Online](https://devblogs.microsoft.com/microsoft365dev/prevent-throttling-in-your-application-by-using-ratelimit-headers-in-sharepoint-online/)
### How to decorate your HTTP traffic?
@@ -167,21 +229,23 @@ What is the definition of undecorated traffic?
What are the recommendations?
- If you've created an application, the recommendation is to register and use AppID and AppTitle – This will ensure the best overall experience and best path for any future issue resolution. Include also the User Agent string information as defined in the following step.
> [!NOTE]
> Refer to the [Microsoft identity documentation](/azure/active-directory/develop/), such as the [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app) page, for information on creating an Azure AD application.
- Make sure to include the User-Agent string in your API call to SharePoint with the following naming convention
| Type | User Agent | Description |
| ---------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| ISV Application | ISV&#124;CompanyName&#124;AppName/Version | Identify as ISV and include Company Name, App Name separated by a pipe character and then add Version number separated with a slash character |
|------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| ISV Application | ISV&#124;CompanyName&#124;AppName/Version | Identify as ISV and include Company Name, App Name separated by a pipe character and then add Version number separated with a slash character |
| Enterprise application | NONISV&#124;CompanyName&#124;AppName/Version | Identify as NONISV and include Company Name, App Name separated by a pipe character and then adding Version number separated with a slash character |
- If you're building your own JavaScript libraries, which are used to call SharePoint Online APIs, make sure that you include the User-Agent information to your HTTP request and potentially register your web application also as an Application, where suitable.
> [!NOTE]
> The format of the user agent string is expected to follow [RFC2616](http://www.ietf.org/rfc/rfc2616.txt), so please follow up on the above guidance on the right separators. It is also fine to append the existing user agent string with the requested information.
## Common throttling scenarios in SharePoint Online
The most common causes of per-user throttling in SharePoint Online are client-side object model (CSOM) or Representational State Transfer (REST) code that performs too many actions too frequently.
@@ -194,10 +258,10 @@ The most common causes of per-user throttling in SharePoint Online are client-si
A single process dramatically exceeds throttling limits, continually, over a long period.
- You used web services to build a tool to synchronize user profile properties. The tool updates user profile properties based on information from your line-of-business (LOB) human resources (HR) system. The tool makes calls at too high a frequency.
- You're running a load-testing script on SharePoint Online and you get throttled. Load testing isn't allowed on SharePoint Online.
- You customized your team site on SharePoint Online, for example, by adding a status indicator on the Home page. This status indicator updates frequently, which causes the page to make too many calls to the SharePoint Online service - this triggered throttling.
- Running the OneDrive Sync client while also running migration applications or applications that crawl sites and write back data can result in high request volumes that may trigger throttling.
- You used web services to build a tool to synchronize user profile properties. The tool updates user profile properties based on information from your line-of-business (LOB) human resources (HR) system. The tool makes calls at too high a frequency.
- You're running a load-testing script on SharePoint Online and you get throttled. Load testing isn't allowed on SharePoint Online.
- You customized your team site on SharePoint Online, for example, by adding a status indicator on the Home page. This status indicator updates frequently, which causes the page to make too many calls to the SharePoint Online service - this triggered throttling.
- Running the OneDrive Sync client while also running migration applications or applications that crawl sites and write back data can result in high request volumes that may trigger throttling.
- **Unsupported use cases**
@@ -206,15 +270,17 @@ The most common causes of per-user throttling in SharePoint Online are client-si
- **Creating multiple AppIDs for the same application**
Don't create separate AppIDs where the applications essentially perform the same operations, such as backup or data loss prevention. Applications running against the same tenant ultimately share the same resource as the tenant. Historically some applications have tried this approach to get around the application throttling but ended up exhausting the tenant’s resource and causing multiple applications to be throttled in the tenant.
## Scenario specific limits
### When using app-only authentication with Sites.Read.All permission
When you're using SharePoint Online search APIs with app-only authentication and the app having Sites.Read.All permission (or stronger), the app will be registered with full permissions, and is allowed to query all your SharePoint Online content (including the user’s private OneDrive for Business content).
When you're using SharePoint Online search APIs with app-only authentication and the app having **Sites.Read.All** permission (or stronger), the app will be registered with full permissions, and is allowed to query all your SharePoint Online content (including the user’s private OneDrive for Business content).
To ensure the service remains fast and reliable, queries using such permission are throttled at 25 requests per second. The search query will return an HTTP 429 response. When waiting for throttling recovery, you should ensure to pause all search query requests you may be making to the service using similar app-only permission. Making more calls while receiving throttle responses will extend the time it takes for your app to become unthrottled.
### When searching using delegated user permissions
Searching with delegated user permissions occurs when an application submits a search query request with the signed-in user's permissions. Examples of delegated requests are as follows: the search box on a SharePoint page, a search-based web part or custom application embedded on a SharePoint page, and a Power Automate workflow querying for item information.
To ensure service stability, the service will throttle delegated user requests that exceed 10 requests per second per user. This per-user limit aggregates across all requests from all apps. If a single user sends more than 10 search query requests per second, an HTTP 429 is returned. The requesting application should wait the duration of the timeout specified in the response header before sending subsequent requests. When designing search-based applications, SharePoint pages, and workflows, implementors should make sure the page and application do not exceed 10 requests per second in aggregate and handle 429 throttling responses. For more information and guidance on page design and search optimization, see [Optimize search requests in SharePoint Online modern site pages](/microsoft-365/enterprise/modern-search-optimization) and [Use the Page Diagnostics tool for SharePoint Online](/microsoft-365/enterprise/page-diagnostics-for-spo).
@@ -225,14 +291,19 @@ When searching using a result source that requests people results, we may thrott
If you have applications or components, that are causing your people search requests to get throttled, we recommend that you:
1. Consider if the requests are necessary for your application. For example, if you're using a custom search site, that makes many simultaneous queries, check whether some of those requests can be removed without any significant impact to your organization's search experience. Alternatively, consider trying our modern people search experience in [Microsoft Search](/microsoftsearch/get-started-search-in-sharepoint-online) by searching from the [SharePoint](https://sharepoint.com/) start page. People search in Microsoft Search has been optimized for better performance and more relevant results.
1. Consider if the requests are necessary for your application. For example, if you're using a custom search site, that makes many simultaneous queries, check whether some of those requests can be removed without any significant impact on your organization's search experience. Alternatively, consider trying our modern people search experience in [Microsoft Search](/microsoftsearch/get-started-search-in-sharepoint-online) by searching from the [SharePoint](https://sharepoint.com/) start page. People search in Microsoft Search has been optimized for better performance and more relevant results.
1. Avoid making concurrent requests. For example, instead of issuing 10 requests all at once, issue them consecutively - only issue the next query after the previous one has been completed. You may need to consider caching these results if you need them quickly, for example of a page load.
1. Try consolidating the requests into a single query. For example, instead of making 10 simultaneous queries for `WorkEmail:user1@constoso.com`, `WorkEmail:user2@constoso.com`,..., `WorkEmail:user10@contoso.com`, try the single query, `WorkEmail:user1@constoso.com WorkEmail:user2@constoso.com ... WorkEmail:user10@contoso.com`.
1. Consider using the [Microsoft Graph API](/graph/search-concept-person) if a high-request-volume scenario (in excess of 25 requests per second) is truly necessary.
### When accessing OneDrive sites
When a client makes excessive attempts to access many OneDrive site collections that do not exist, we may throttle requests from that client's IP address. The client will receive an HTTP 429 response when accessing any OneDrive site collection during the throttling period.
### Multi-Geo Customers and throttling
When a customer enables throttling, each gets their own limits (usage measurement not shared across geos). For the limits that are dependant on licenses count, the total tenant user licenses count is used (total users across all geos).
## What should you do if you get blocked in SharePoint Online?
Blocking is the most extreme form of throttling. We rarely ever block a tenant unless we detect long-term, excessive traffic that may threaten the overall health of the SharePoint Online service. We apply blocks to prevent excessive traffic from degrading the performance and reliability of SharePoint Online. A block - which is placed at the app or user level - prevents the offending process from running until you fix the problem. If we block your subscription, you must take action to modify the offending processes before the block can be removed.
@@ -246,3 +317,4 @@ If we block your subscription, we'll notify you of the block in the Office 365 M
- [Microsoft Graph dev center](/graph)
- [Microsoft Graph throttling guidance](/graph/throttling)
- [Prevent throttling in your application by using RateLimit headers in SharePoint Online](https://devblogs.microsoft.com/microsoft365dev/prevent-throttling-in-your-application-by-using-ratelimit-headers-in-sharepoint-online/)
- [Four options for site analytics](https://techcommunity.microsoft.com/blog/microsoft_graph_data_connect_for_sharepo/four-options-for-sharepoint-site-analytics/4076416)