SharePoint Migration API throttling: budgets, Retry-After and workers

How throttling is measured

SharePoint Online measures throttling per tenant and application pair. Every request an app makes to a tenant counts against that pair's budget, regardless of which machine or which user sent it. Microsoft explicitly warns against creating multiple App IDs to evade limits, and asks migration vendors to register one App ID per product rather than one per customer or per job. A tool that hands out a fresh app registration for every migration is doing it wrong.

Microsoft Graph adds a second layer with published numbers. For SharePoint and OneDrive through Graph, the resource unit budget per app per tenant is 1,200,000 resource units per 24 hours for tenants with up to 1,000 licences, scaling up to 6,000,000, and 1,250 to 6,250 resource units per minute. Ingress and egress are capped at 400 GB per hour per app per tenant. Across all tenants, an app is limited to 130,000 requests per 10 seconds. SharePoint CSOM and REST calls have no fixed resource unit cost but are throttled more than Graph, which is why Microsoft recommends Graph first where it has coverage.

The headers that tell you where you stand

Microsoft signals throttling in three ways, and a tool should read all of them rather than only reacting to failure.

• `Retry-After` on an HTTP 429 or 503 response says how many seconds to wait. Honouring it exactly is the single most important behaviour; retrying sooner extends the penalty and can lead to the app being blocked.
• `x-ms-throttle-limit-percentage` on Graph responses reports how close the app is to its limit, so a tool can slow down proactively, at 80 percent say, before the first 429 arrives.
• `x-ms-resource-unit` on Graph responses reports what a request cost, which lets a tool budget rather than guess.

The Migration API adds a subtlety. Once a package is submitted with CreateMigrationJobEncrypted, Microsoft processes it on its own schedule and reports progress through GetMigrationJobProgress, which is replacing the older Azure Queue status route during the second half of 2026. Throttling on the polling calls does not stop the job; it only delays your knowledge of the result. A tool that abandons polling under throttling loses the per-item error detail, which lives only in Microsoft's encrypted per-job logs and is retrievable for a limited time.

Four behaviours a migration tool must have

1. App-only authentication with a certificate. Microsoft states that migration solutions should only use app-based authentication and that user mode triggers increased throttling. Certificate credentials are throttled less aggressively than client secrets, and they cannot be pasted into a ticket.
2. Traffic decoration. Every request should carry a User-Agent of the form ISV|Company|Product/Version. Microsoft asks for it explicitly so that migration traffic can be identified as such. ShareShift sends ISV|Cameron Shields|ShareShift/<version> on every call.
3. Back-off that honours Retry-After, with exponential back-off and jitter for transient errors that carry no header, and a client-side ceiling on requests per minute applied before Microsoft's own limits are reached.
4. Package discipline. Packages of 100 to 250 MB or about 250 items, single large files in their own packages, fewer than 5,000 jobs queued, and parallel work spread across different site collections, which is Microsoft's own recommendation for throughput.

# What a decorated, well-behaved request looks like
User-Agent: ISV|Cameron Shields|ShareShift/0.4.0
Authorization: Bearer <app-only token from a certificate credential>

# What the service sends back when you must wait
HTTP/1.1 429 Too Many Requests
Retry-After: 120

Measured on 7 September 2026 with those four behaviours in place: 2,500 files in 10 packages with 4 in flight took 8 minutes 16 seconds end to end with zero throttling responses; the first concurrent batch produced 40 transient item-level errors (about 1.6 percent) which the automatic retry pass cleared. That is one run on one tenant, quoted to show the shape of a healthy run rather than as a benchmark.

Why more workers do not add API budget

The budget is per app per tenant. Ten workers pointed at the same destination tenant share one budget, so the eleventh 429 arrives at the same moment whether one machine or ten sent the requests. Vendors who license per machine or per concurrent migration are, in effect, selling parallelism that Microsoft caps upstream.

What a worker does buy is real, and it is worth being precise about it:

• Upload bandwidth: packaging, encrypting and pushing blobs to Microsoft's containers is bound by the worker's network and CPU, and Microsoft's ingress cap of 400 GB per hour per app per tenant is far above what one office link delivers.
• Reach: a worker inside a different network segment or site can read a file share the first worker cannot.
• Separate tenants: an MSP running migrations into ten client tenants has ten separate budgets, and a worker per tenant uses each of them.
• Concurrency within a worker: because the Migration API is asynchronous, one worker can keep several packages in flight and poll them together. ShareShift allows unlimited concurrent jobs per worker for this reason, and includes three workers on every plan.

When to run, and what to cap

Microsoft applies tighter limits to background applications during weekday daytime in the tenant's region, which makes scheduling the cheapest optimisation available. A migration that runs Friday evening to Monday morning, and overnight on weekdays, will see fewer 429s than the same migration run at 11am on a Tuesday, with no other change.

ShareShift exposes three caps per run for exactly this: a maximum number of packages in flight, an upload rate in megabits per second shared across every parallel blob upload, and a client-side ceiling on requests per minute applied ahead of Microsoft's own handling. Combined with schedule windows in wall-clock time that cross midnight correctly and survive daylight saving changes, they let a migration coexist with a busy tenant rather than fight it. The pause and resume article explains how windows and caps interact with packages in flight.

When throttling does hit, the right reaction is to wait exactly as instructed and carry on, not to add machines, not to create another app registration, and not to open a ticket. Microsoft has said what it will and will not do. A tool built for the Migration API from the start makes that reaction automatic; the ShareGate comparison sets out how ShareShift and ShareGate differ here, and the pricing page explains why workers rather than machines or users are the licensed unit.

Frequently asked questions