Polishing throttling doc

Author: VesaJuvonen

docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md

@@ -1,7 +1,7 @@
 ---
 title: Avoid getting throttled or blocked in SharePoint Online
-description: Find out about throttling in SharePoint Online and learn how to avoid being throttled or blocked. .
-ms.date: 06/07/2022
+description: Find out about throttling in SharePoint Online and learn how to avoid being throttled or blocked.
+ms.date: 06/29/2022
 ms.prod: sharepoint
 ms.assetid: 33ed8106-d850-42b1-8d7f-5ba83901149c
 ms.localizationpriority: high
@@ -33,7 +33,7 @@ For requests that a user performs directly in the browser, SharePoint Online red
 For requests that an application makes, including Microsoft 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 is not ready to handle the request. The common cause is that the service is experiencing 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 temporary load spikes then expected.
 
 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.
 
@@ -43,20 +43,20 @@ If the offending application continues to exceed usage limits, SharePoint Online
 
 Throttling limits the number of calls and operations collectively made by applications on behalf of a user to prevent overuse of resources.
 
-That said, it is rare for a user to get throttled in SharePoint Online. The service is robust, and it is 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.
+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.
 
 ### Application Throttling
 
 In addition to throttling by user account, limits are also applied to applications in a tenant. 
 
 Every application has its own limits in a tenant, which are based on the number of licenses purchased per organization (see the plans listed on [SharePoint Limits](/office365/servicedescriptions/sharepoint-online-service-description/sharepoint-online-limits#limits-by-plan) for licenses included). Every request that an application makes across all API endpoints, including Microsoft Graph, CSOM and REST, counts towards the application’s usage.
 
-SharePoint provides a variety of 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.
+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 |
 
@@ -74,28 +74,28 @@ In terms of API costs, Microsoft Graph APIs have a predetermined resource unit c
 > [!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 details 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 is a multi-item query. The delta request without a token is considered a multi-item query and costs 2 resource units per request.
+Delta with a token is the most efficient way to scan content in SharePoint, and we talk more in details 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 do not have a predetermined resource unit cost and they usually consume more resource units than Microsoft Graph APIs to achieve the same functionality. And 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 over CSOM and REST APIs when possible.
+CSOM and REST don't have a predetermined resource unit cost and they usually consume more resource units than Microsoft Graph APIs to achieve the same functionality. And 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 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 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 own 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. 
+Although each application has its own 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. 
 
 ## How to handle throttling?
 
 Below is a quick summary of the best practices to handle throttling:
 - Reduce the number of concurrent requests
 - Avoid request spikes
 - Choose Microsoft Graph APIs over CSOM and REST APIs when possible
-- Leverage the `Retry-After` and `RateLimit` HTTP headers
+- 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)
 
 As stated earlier, Microsoft Graph is cloud born APIs that have the latest improvements and optimizations. In general, Microsoft Graph consumes less resource than CSOM and REST to achieve the same functionality. Hence, adopting Microsoft Graph can improve application's performance and reduce throttling.
 
-If you do run into throttling, we require leveraging the `Retry-After` HTTP header to ensure minimum delay until the throttle is removed. The `RateLimit` HTTP headers send you early signals when you are close to limits and you can proactively reduce requests to avoid hitting the throttle.
+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.
 
 ### Retry-after header
 
@@ -105,7 +105,7 @@ Honoring the `Retry-After` HTTP header is the fastest way to handle being thrott
 
 Throttled requests count towards usage limits, so failure to honor `Retry-After` may result in more throttling. In other words, aggressive retries work against calling applications because even though the calls fail, they still count towards usage limits. Honoring the `Retry-After` HTTP header will ensure the shortest delay and reduce wasting quotas in throttled requests.
 
-### RateLimit headers - beta
+### RateLimit headers - preview
 
 In addition to the `Retry-After` header in the response of throttled requests, SharePoint Online also returns the [IETF RateLimit headers](https://github.com/ietf-wg-httpapi/ratelimit-headers) for selected limits in certain conditions to help applications manage rate limiting. We recommend applications to take advantage of these headers to avoid hitting throttle. 
 - `RateLimit-Limit` contains the limit in the current time window.
@@ -115,7 +115,7 @@ In addition to the `Retry-After` header in the response of throttled requests, S
 > [!NOTE]
 > These headers are currently in **beta** and subject to change. At the time when the headers were adopted, the IETF specification was in draft. The current implementation is based on the [draft-03](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-03) of the IETF specification. There is the potential for changes when the specification is final, and we will adapt to those changes in the future.  
 
-The `RateLimit` headers are returned on a **best-efforts** basis, so applications may not receive the headers under all conditions. Additionally, there are other limits that are not presented in the `RateLimit` headers, so applications can get throttled even before reaching the limit described in the `RateLimit` headers. 
+The `RateLimit` headers are returned on a **best-efforts** basis, so applications may not receive the headers under all conditions. Additionally, there are other limits that aren't presented in the `RateLimit` headers, so applications can get throttled even before reaching the limit described in the `RateLimit` headers. 
 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                                                                                                      |
@@ -141,7 +141,7 @@ 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 do not support. In this case, the request is throttled and the `RateLimit` headers are not returned to avoid confusion although the condition to return the headers is satisfied.
+- 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
@@ -154,7 +154,7 @@ Well-decorated traffic will be prioritized over traffic that isn't properly deco
 What is the definition of undecorated traffic?
 
 - Traffic is undecorated if there's no AppID/AppTitle and User Agent string in API calls to SharePoint Online. The User Agent string should be in a specific format as described below.
-- If you are developing a web application executing in the browser, most modern browsers don't allow overwriting the User Agent string and you don't need to implement it.
+- If you're developing a web application executing in the browser, most modern browsers don't allow overwriting the User Agent string, and you don't need to implement it.
 
 What are the recommendations?
 
@@ -197,31 +197,31 @@ The most common causes of per-user throttling in SharePoint Online are client-si
 
 - **Creating multiple AppIDs for the same application**
 
-    Do not 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 of 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.
+    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 of 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 are 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 user’s private ODB 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 user’s private ODB 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 with 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 additional calls while receiving throttle responses will extend the time it takes for your app to become unthrottled.
+To ensure the service remains fast and reliable, queries using such permission are throttled at 25 requests per second. The search query will return with 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 for people search results
 
 When searching using a result source that requests people results, we may throttle any requests exceeding a limit of 25 requests per second. This limit applies jointly to all requests using the out-of-the-box "Local People Results" result source and all requests using custom people search result sources.
 
-If you have applications or components which are causing your people search requests to get throttled, we recommend that you:
-1. Consider if the requests are really necessary for your application. For example, if you are using a custom search site which 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](http://sharepoint.com/) start page. People search in Microsoft Search has been optimised for better performance and more relevant results.
-2. 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 completed. You may need to consider caching these results if you need them quickly, for example on a page load.
+If you have applications or components, which 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, which 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](http://sharepoint.com/) start page. People search in Microsoft Search has been optimized for better performance and more relevant results.
+2. 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 completed. You may need to consider caching these results if you need them quickly, for example of a page load.
 3. Try consolidating the requests into a single query. For example, instead making 10 simultaneous queries for `WorkEmail:[email protected]`, `WorkEmail:[email protected]`,..., `WorkEmail:[email protected]`, try the single query, `WorkEmail:[email protected] WorkEmail:[email protected] ... WorkEmail:[email protected]`.
 4. Consider using the [Microsoft Graph API](/graph/people-example#search-people) if a high-request-volume scenario (in excess of 25 requests per second) is truly necessary.
 
 ## 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.
 
-If we block your subscription, we will notify you of the block in the Office 365 Message Center. The message describes what caused the block, provides guidance on how to resolve the offending issue, and tells you who to contact to get the block removed.
+If we block your subscription, we'll notify you of the block in the Office 365 Message Center. The message describes what caused the block, provides guidance on how to resolve the offending issue, and tells you who to contact to get the block removed.
 
 ## See also