Updated Guidance around SharePoint Web Service Identification and Throttling

We’ve updated and extended our guidance around throttling behaviors and web services for SharePoint in Office 365 to focus on identification as a path towards reducing throttling in Office 365. Please read our updated documentation to learn the latest around throttling for SharePoint in Office 365.

As background, SharePoint web services in Office 365, including REST APIs and CSOM endpoints, include throttling mechanisms that are designed to protect the overall health of SharePoint services. After patterns of repeated, abnormally high usage, SharePoint web service callers will receive “429 Too Many Requests” responses, which indicates that callers retry their service requests at a later time. In some cases, this throttling can impact all inbound service requests for specific SharePoint sites.

For this reason, it is important to be able to identify incoming web traffic so that the best possible user experience can be delivered. Most web service callers are already inherently identified through their application identifier as they call into SharePoint. Where possible, we are recommending that developers register for an Application Identifier, using Add-in registration mechanisms. Using an application identifier is sufficient to ensure that your web service experiences preferred throttling behavior.

As a best practice, we are also recommending that SharePoint web service callers identify their service through the UserAgent HTTP Header – even if you are already using an application identifier. Specifically, developers should annotate their web requests with UserAgent strings in a particular structured format, to identify the type of service:

• Independent Software Vendors should use a UserAgent of the form ISV|CompanyName|AppName/Version.
• Enterprise Developers should use a UserAgent of the form NONISV|CompanyName|AppName/Version.

Where for CompanyName, AppName, and Version, you should include the Company Name, Application Name separated by vertical bar (pipe) character, and add Version number as the final section separated with a slash character.

Read more guidelines around these annotations via the documentation.

Note that every web service client will potentially experience throttling at various points in its lifecycle, so it is important to adapt your code to support this. Typically, the correct behavior is to respect the 429 response and retry the request based on the retry-value in the 429 message. For more information, see the main article around throttling – application of these guidelines can improve overall responsiveness of your applications, and of SharePoint in Office 365.