Throttling Policies and the EWSFindCountLimit

One of my favorite Exchange Web Services (EWS) methods is FindItem, primarily because it was the first Web method I wrote when I joined the EWS team long, long ago. Since then, it has undergone lots of optimizations, feature changes, and so on, to make it what it is today. One of the Exchange 2010 changes to FindItem (and FindFolder) is protective in nature – Exchange doesn’t want to drown a Client Access server just because someone decides to pull down the entire contents of their mailbox. This protective change is governed by the EWSFindCountLimit throttling policy parameter.

When a FindItem request comes in and the caller is authenticated, EWS obtains the caller’s budget. Every item (or folder in the case of FindFolder) that EWS processes for the current FindItem request is counted against the budget’s EWSFindCountLimit. As soon as the response is sent back to the caller, the find count charge for the current call is released. Why do we do this? Because items and folders that are waiting to be returned in a response take up memory on the Client Access server.

You will soon discover that budgets have a larger scope than a single request. If a caller makes two concurrent EWS FindItem requests that return 10 items each, the EWSFindCountLimit charge against that caller’s *single* budget is…20. When the first request returns, it will drop to 10 (because those items can now be garbage collected) and then when the second request returns it will drop to 0. It should be relatively obvious that we are trying to limit the caller’s memory footprint on the Client Access server.

What happens, though, when a caller reaches the limit? Well, that depends on whether the caller is being a “good EWS citizen”. And what makes an EWS citizen “good”? Well, in the context of EWSFindCountLimit, a good EWS citizen will do all their FindItem calls by using paging rather than by requesting the entire result set each time. Assume, for a moment, that the EWSFindCountLimit value is 1000 and a bad EWS citizen makes a FindItem call without paging. Let’s further say that the query will return 1001 items. EWS certainly can’t truncate the results, as the caller is expecting, to receive ALL the data back. And EWS can’t turn a non-paged FindItem call into a paged one, as the caller would not expect to check for such a response. So what does EWS do? If the call has a RequestServerVersion that is earlier than Exchange2010, you will receive a failure response with an error code of ErrorServerBusy. If your RequestServerVersion is Exchange2010, you will get back the following response:

<s:Body xmlns:xsi=”” xmlns:xsd=””>
  <m:FindItemResponse xmlns:m=”” xmlns:t=””>
      <m:FindItemResponseMessage ResponseClass=”Error”>
        <m:MessageText>You have exceeded the maximum number of objects that can be returned for the find operation. Use paging to reduce the result size and try your request again.</m:MessageText>
          <t:Value Name=”PolicyLimit”>1000</t:Value>

Very interesting. For kicks, let’s reduce the EWSFindCountLimit and cycle IIS to pick up the changes (ah yes, the joys of having your own test box to beat upon). Open the Exchange 2010 Management Console as an Exchange Admin and run the following (New-ThrottlingPolicy is only available to administrators, for obvious reasons):

New-ThrottlingPolicy –Name “FooPolicy” –EWSFindCountLimit 1
Set-Mailbox JohnDoe –ThrottlingPolicy FooPolicy

Now, on my test box, I created 6 email messages in John Doe’s Drafts folder.  Let’s call FindItem again, but use indexed paging.  Here is my request:

    <t:RequestServerVersion Version=”Exchange2010″/>
<FindItem xmlns=””
           xmlns:t=”” Traversal=”Shallow”>
            <t:FieldURI FieldURI=”item:Subject”/>
    <IndexedPageItemView BasePoint=”Beginning” Offset=”0″ MaxEntriesReturned=”10000″/>
           <t:DistinguishedFolderId Id=”drafts”/>              

And the response…

<s:Body xmlns:xsi=”” xmlns:xsd=””>
  <m:FindItemResponse xmlns:m=”” xmlns:t=””>
      <m:FindItemResponseMessage ResponseClass=”Success”>
        <m:RootFolder IndexedPagingOffset=”1″ TotalItemsInView=”6″ IncludesLastItemInRange=”false”>
              <t:ItemId Id=”AAMkA…”/>

Whoa – wait a second! There were 6 messages to return, I asked for 10000, but it only returned 1 of them to me! What happened? Well, given that the caller’s EWSFindCountLimit is 1, EWS will NOT return more than 1 record to the user (at a time). However, because the caller was a good Exchange citizen and made a paged request, EWS can “fix up” the result because the user will (read: should) understand that EWS might not return ALL the items. The caller will instead look at the IncludesLastItemInRange attribute and, if it is false, make another FindItem request with the new Offset and continue until IncludesLastItemInRange returns true. If this behavior seems odd to you, consider that this is exactly how the various network streams in the Microsoft .NET framework behave – you continue reading from the stream until the stream reports that it has no more data to read.

So, the moral of the story is: Always use a paging mechanism when calling FindItem or FindFolder. Wisely, the Exchange Web Services Managed API forces you to do so by requiring an ItemView to be passed into FindItem:

service.FindItems(new FolderId(WellKnownFolderName.Drafts), new ItemView(10000));

Now that you know, there is no excuse for failing to use a page view 🙂

David Sterling
Exchange Web Services
Inside Microsoft Exchange Server 2007 Web Services

Comments (14)

  1. Ma^ says:


    Can you please give a sample code on how to implement this one? The paging stuff. I'm having problem knowing if there is still available item to read from the response returned by FindItem.

    This would be a great help.



  2. Carl Clark says:

    Hi Thom,

    Thanks for the article.  I have been coding around in circles trying to find the reason for a call to FindItems not returning results as I expect and am still chasing my tail.  

    I have posted this question…/cbd1c1b7-c1a0-4a8b-95dc-bcde1eac4870 as I am starting to feel like it may be a bug within Exchange Web Services.

    Can you cast some light?  Or at least direct me to the best place to get a resolution on this.



  3. Yaniv says:

    Hi, I have read your article .. and I use it in my project.. the problem is:

    my EWS project works fine, but every x minutes or hours (in my case I get everyday about half-hour – one hour in 24 hours) I get timeout respond from the exchange server and it happen everyday

    I send request to server every 5 minutes.

    Maybe you know why it happen (what a reason of it)?

  4. Yaniv says:

    Forgot to write "Thanks" in previous comment 🙂

    So thanks for answers 🙂

  5. David says:

    What version of Exchange and is this on-premise or Exchange Online/Office 365?  You might be hitting throttling limits depending on how much you are calling EWS.  When you have put too much pressure on it, it will begin to insert what we call "micro delays" to decrease your throughput.  If on-prem, you should be able to get your Exchange admin to look at the protocol logs to see what (if any) delays were added to your calls and the reason for the long call.

  6. Yaniv says:

    Thanks for answer.

    I'm using Exchange Online/Office 365 (using exchange 2010 version)

    I'm calling EWS every 5 minutes.. (in case if connection is still works, next call will not happen.)

    so what is possible solution for this case? I use this line of code:

    FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, new ItemView(10000));

    we also tried to use timeout to increase default timeout, but it not help us, still get timeouts during a day (24 hours)

    about "able to get your Exchange admin to look at the protocol logs" – I don't know if we can do it , because it's Microsoft servers, so I guess that we need to call to Microsoft helpdesk and ask them to check this protocol log – isn't?

    thanks very much again for advice!! :):)

  7. Yaniv says:

    Another question:  is it possible that I still can get timeouts if I'll use POP3 or IMAP4 instead using EWS to get emails from server?

    Thanks again..

  8. David says:

    Hmmm – I would not try to fetch 10k items in one call.  That could be why your request is timing out.  Instead, try to grab in smaller chunks – maybe 100 at a time and continue fetching until the resulting offset tells you that you are at the end.  Just curious – what is the goal here?  Are you trying to fetch down the entire mailbox?

  9. Yaniv says:

    Thank you very much for your answers 🙂

  10. Orit says:

    Hi David,

    I'm Yaniv's colleague, thank you for your replies.

    Yes, we are trying to fetch the entire mailbox, but generally there will be around 10-20 max. items in inbox because every item which is already processed is deleted. So eventuallly although calling for 10k items we are fetching around 10-20  items. When that is the case, you think calling for 100 items only should solve the problem?

    Thanks again,


  11. lynam says:

    Hi Orit and Yaniv, I have the exact same timeout problem and I'm currently calling for 1000 items. I'm pretty sure my problem is related to throtting as I get my timeout in the peak usage hours (backup time and at the beginning of the day when everyone arrives to work)

    I also process items from a specific folders. So, like you, there can't be many items in the folder since they are moved once they are processed. I use streaming notifications to get new items but at each subscription renewal,, I do a FindItems in the folders to catch messages that may have been missed by the streaming notification (I'm maybe to cautious, but we need to make sure no messages are forgotten. But based on my log, in about a month of production, it hasn't proved useful… maybe I should disable this part.)

    Did changing to 100 items solved your problems?


  12. mahesh says:

    I have a task where i need to check the emails delivered to my mailbox and read them ,based on subject i have to do some task. But for demo purpose I have put only the basic functionality of just updating the email read status

    The basic connection and creating service object everything is fine:


    NetworkCredential credentials = new NetworkCredential(securelyStoredEmail, securelyStoredPassword);

    ExchangeService _service = new ExchangeService(ExchangeVersion.Exchange2010_SP2);

    _service.Credentials = credentials;



    Here Everything works fine. However I will invoke the below method for every 60s using observable event of reactive linq. THis is to go and poll the my emailbox and read 100 emails for every 60 seconds.

    Everything works fine till sometime. Sometimes when the control reaches the line of code inside parallel.foreach loop, it shows error message like 'server cannot process this request now. Please try later' something like this. THis error comes exactly at the line


    var email = EmailMessage.Bind(_service, findItemsResult.Id, emailProps);


    so for every 60 seconds, i will get this error sometimes.sometimes it works fine.

    Below is the method which is executed for every 60seconds. Its like i try to read the emails from "" for every 60s and i vil get the error 'server cannot process'.

    internal void GetEmailsFrommymailbox()




    var view = new ItemView(100);

    var userMailbox = new Mailbox(userMailbox);

    var folderId = new FolderId(WellKnownFolderName.Inbox, userMailbox);

    SearchFilter sf = new SearchFilter.SearchFilterCollection(LogicalOperator.And,

    new SearchFilter.IsEqualTo(EmailMessageSchema.IsRead, false));

    var findResults = _service.FindItems(folderId, sf, view);

    var emailProps = new PropertySet(ItemSchema.MimeContent, ItemSchema.Body,


    Parallel.ForEach(findResults, findItemsResult =>


    ///////////// this is the line where i get error////////

    var email = EmailMessage.Bind(_service, findItemsResult.Id, emailProps);

    //// above is the place where i get error

    var emailMatching = email;



    email.IsRead = true;



    catch (Exception emailreadFromBccException)


    Logger.Warn(emailreadFromBccException + " Unable to update email read status");





  13. Eliot says:

    I have my request limited to 900 by the MaxEntriesReturned but when I call my request with 1001 emails in inbox it still doesn't work

  14. Tse says:


    I've configured an application to use a specific service account to access my users' mailboxes. I've created and associated a throttling policy with this service account (no limit, null values).

    In reviewing the event logs, I come across an error that seems to suggest the unlimited throttling policy is not being honored.

    Microsoft.Exchange.Data.Directory.SystemConfiguration.OverBudgetException: This operation exceeds the throttling budget for policy part 'CAS', budget type: 'EWS'. Suggested backoff time 27227 ms. at Microsoft.Exchange.Data.Directory.Budget.CheckOverBudget(CostType costType) at Microsoft.Exchange.Services.Core.PushSubscription.BuildNotification()

    Does anyone know what (specifically) 'policy part 'CAS', budget type: 'EWS'.' is referring to?