Share via

Gotchas - Microsoft Graph/Outlook REST API throttling, best practices

  • Article

In recent times, I was working with this customer where they make Graph API calls,

Say,
GET https://graph.microsoft.com/v1.0/users/YYY\@XXX.onmicrosoft.com/mailFolders/inbox/messages?$skip=0&$top=30&$select=bodypreview,categories,conversationid,from,hasattachments,id,isdraft,isread,lastmodifieddatetime,parentfolderid,receiveddatetime,replyto,sender,sentdatetime,subject,torecipients
and few other GET (read operations of mail folders/single item handles specifically) and few POST/PATCH calls.

They noticed, once the throttling threshold is exceeded, Microsoft Graph limits any further requests from that client for a period of time.

We looked at the HTTP Status code 429 response. When throttling occurs, Microsoft Graph returns HTTP status code 429 (Too many requests), and the requests fail. A suggested wait time is returned in the response header of the failed request.

{
"error": {
"code": "UnknownError",
"message": "",
"innerError": {
"request-id": "xxxxxx-esse0-4480-90d4-xxxxxxx",
"date": "2018-05-05T09:12:35"
}
}
}

The above is one of the such throttling that I noticed. But throttling behavior can depend on the type and number of requests. In general, Microsoft Graph API is designed to handle a high volume of requests. If an overwhelming number of requests occurs, throttling helps maintain optimal performance and reliability of the Microsoft Graph service. But the throttling limits vary based on the scenario and based on your implementation.

Best practices to handle throttling:
In such scenario’s, I would try one of the following best practices and see if it helps.

  • Reduce the number of operations per request.
  • Reduce the frequency of calls.
  • Avoid immediate retries, because all requests accrue against your usage limits.
  • Reduce the number of GET call for single items.
  • If you do run into throttling, try reduce the number/frequency of calls until no more throttling occurs.
  • When you design your application please pay attention and try to build the ability to handle the clear errors returned to you once you have hit such a limit, and re-ping the endpoint using the suggested time-frames and methods.
  • Being the app developer I would recommend when you implement error handling, use the HTTP error code 429 to detect throttling. The failed response includes the Retry-After field in the response header. Backing off requests using the Retry-After delay is the fastest way to recover from throttling because Microsoft Graph continues to log resource usage while a client is being throttled. So you can try this,
    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.

Related documentation:

For Outlook API & Microsoft Graph, refer Jason’s blogpost https://blogs.msdn.microsoft.com/exchangedev/2017/04/07/throttling-coming-to-outlook-api-and-microsoft-graph/
You can find information on throttling at Microsoft Graph throttling guidance.
For a broader discussion of throttling on the Microsoft Cloud, see Throttling Pattern.
For SharePoint online related ones, please refer https://docs.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online

Hope this helps.