Updated Guidance around Identity and SharePoint web service throttling

Mike Ammerlaan

Hello everyone,


We've updated our guidance around throttling and usage of SharePoint web services, like REST and CSOM.  While every app at some point may potentially get throttled (i.e., a 429 response to a web service request) and you'll want to design for that -- you can decrease the overall likelihood of throttling by adding an identity to your web service requests.  This can be done either by using an App Identifier to your app (which many of you are already doing, today) or updating your UserAgent.   Indeed, we recommend that all web service consumers add an identifying string to their UserAgent as a best practice.  Read more about throttling and identities on this page.


Thanks for taking a look at our updated throttling guidelines!


-- Mike

6 Replies

Thanks for the heads up...we have started to use in some of our developments and we are seeing some side effects in Chrome



Little unclear on this one. I have have number of PowerShell and Console applications that communicate with SharePoint Online. Do I need to add this change to each of these or does this only apply to add-ins? If so how? Do I need to registrar the scripts as Addin's and then use the Title added in the AppNewReg.aspx as the AppName as referred to in the documentation?  If I do use the AppNewReg method do I need to do anything with the Secret and Client Id and in addition do I have to update each year when the secret expires? For the Company part of the UserAgent do I need to registrar this somewhere or does it not matter? Can I use the same UserAgent string for different teancies. I may have got all this very confused but the documentation is very unclear and the links do not use the same terminology and the Docs article e.g. Name and Title


Sorry for all the questions but I am quite confused!

Hi Benjamin,

here's some additional context. If you are using user context (not from app), which would be typical setup with console or PowerShell scripts, adding UserAgent string based on the request would be sufficient. You can though only add that by yourself for the console scenario.


If you are using PowerShell or more specifically PnP PowerShell, UserAgent decoration is automatically taken care off. By default, PnP PowerShell uses the following format for the UserAgent - "NONISV|SharePointPnP|PnPCore/{PnP CSOM Core assemblyversion}". This default setting is also used in console application scenario if you are using PnP CSOM Core component. You can override the default setting by using SharePointPnPUserAgent key in app.config, if you prefer to do so.


You do not need to register used Company part anywhere beforehand to be able to us it and you can use the same UserAgent string in different tenants. 

Thank you for the clarification. That makes sense. I will construct one for the console app because it uses a mixture of PnP and CSOM.


Thanks again

I have implemented this successfully for a C# project and am now looking at doing it for PowerShell. I have taken the example in the documentation and implemented it like this:


#Add the User String
Register-ObjectEvent -InputObject $clientContext -EventName ExecutingWebRequest -Action {
$request = $EventArgs.WebRequestExecutor.WebRequest
$request.UserAgent = UserAgentString
This appears to be working

I couldn't get your solution to work because Register-ObjectEvent is asynchronous. Checking with Fiddler shows the User-Agent string is not going over the wire.


This implementation works for me:

param($Source, $EventArgs)
$request = $EventArgs.WebRequestExecutor.WebRequest
$request.UserAgent = "ISV|ItIsI|MyApp/1.0"