HTTP 429 and HTTP 503 in SharePoint Online: throttling and list limits

Fix it now

Microsoft documents 429 as the caller having sent too many requests in a time window and exceeded a predetermined limit, and 503 as the service not being ready to handle the request, commonly through temporary load spikes. Both carry a Retry-After header, and honouring it is documented as the fastest way to stop being throttled.

1. Read the Retry-After header and wait exactly that long. Microsoft states that throttled requests count towards usage limits, so ignoring it produces more throttling, not less.
2. Do not build against RateLimit headers. SharePoint Online does not return or support them; honour Retry-After instead.
3. Identify what is generating the load – a migration tool, a flow, a reporting script – before changing any code.
4. Decorate the traffic with a User-Agent in the documented format: ISV|CompanyName|AppName/Version, or NONISV|CompanyName|AppName/Version for an in-house application. Well-decorated traffic is prioritised.
5. Batch the work rather than making one call per item, and add exponential backoff between batches.
6. For a list view threshold error, index the column the query filters on and narrow the filter so it returns a small set.
7. Check the Service Health Dashboard before assuming it is you. Widespread 503 with no pattern is an incident.

If the job completes without 429s in the log, you are done. If it still throttles at modest volume, the next section covers the published per-second limits and how the cost model works.

Why it happens

SharePoint Online is multi-tenant and the resources behind it are shared. To stop one busy tenant degrading everyone else, the service meters usage and refuses requests once a caller exceeds its allowance. The allowance is not a simple request count – in batching, Microsoft documents that requests in a batch are evaluated individually by resource units – which is why a small number of expensive queries can be throttled while thousands of cheap ones pass without complaint.

Microsoft documents both codes as including a Retry-After header indicating how long the caller should wait, and describes honouring it as the fastest way to handle being throttled, because the service works out the right time dynamically. The warning attached matters as much as the advice: throttled requests still count towards usage limits, so a tight retry loop makes things worse. Two published figures are worth knowing – app-only access with Sites.Read.All is throttled at 25 requests per second, and delegated user permissions at 10 requests per second per user, aggregated across all applications.

The list view threshold is a different limit with the same philosophy. A view showing more than 5,000 items can hit it, and in SharePoint in Microsoft 365 that figure cannot be adjusted – it exists to keep performance predictable on a shared service. An indexed column changes the arithmetic: the service can find the matching rows directly rather than scanning, so a filtered view over a very large list works when the filter is on an indexed column and returns a modest result set.

Full reference

Which limit you are hitting

Headers, and one that does not exist

That middle row costs people real time. RateLimit headers are common enough elsewhere that developers write against them by habit, find nothing, and conclude the service is not sending throttling signals at all. It is – in Retry-After.

The published per-second limits

• Application-only access with Sites.Read.All is throttled at 25 requests per second.
• Delegated user permissions are throttled at 10 requests per second per user, aggregated across all applications using that user’s context.
• Because the delegated limit aggregates, two of your own tools sharing one service account halve what each can do.
• That aggregation is the practical argument for an application identity per workload, ahead of any argument about credentials.

Large lists in more detail

The threshold is 5,000 items in a list view, and in SharePoint in Microsoft 365 it cannot be raised – it exists to keep a shared service predictable. The documented ways to work within it are indexing, filtering, folders, the search box, personal views with fewer items, splitting data across related lists, RSS, working with exported data offline, and using the modern experience, which handles large views better than the classic one. The point of all of them is the same: reduce the number of items the query has to consider, rather than asking the service to consider more.

Designing a job that does not get throttled

1. Decide the identity first: an application identity for background work, one per workload.
2. Decorate the traffic with a User-Agent in the documented format.
3. Batch operations, and request only the fields you need.
4. Honour Retry-After exactly, and add exponential backoff with jitter for anything without a header.
5. Cap concurrency, and schedule bulk work away from the interactive peak.
6. Log correlation identifiers throughout, so an escalation has evidence rather than a description.

Every code this article covers

Confirm the fix worked

1. The job re-runs and completes with no 429 responses in the log.
2. Your client logs show it honouring Retry-After when a throttle does occur, rather than retrying immediately.
3. The affected list view renders without the threshold message.
4. The columns you indexed appear in the list’s indexed columns settings.
5. Background work is running under an application identity with a decorated User-Agent, not under a person’s account.

Questions people ask about this