Following Microsoft Graph's @odata.nextLink and handling 429 throttling and batch limits

What it is

Microsoft Graph's paging guide states that "when there's at least one more page of data available, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results," and that a client "must continue to call Microsoft Graph with the @odata.nextLink property returned in each response until the @odata.nextLink property is no longer returned." Depending on the API, that URL contains "either a $skiptoken or a $skip query parameter" plus the original query parameters, and the paging guide says "don't try to extract the $skiptoken or $skip value and use it in a different request"; the query-parameters reference calls the skip token "an opaque token that references the next page of results". A page "might contain zero or more results", so an empty page with a nextLink is not the end. Client-side paging is available on many endpoints via $top (and, less broadly, $skip/$skipToken); the default and maximum page sizes are endpoint-specific. On throttling, Graph's guidance shows the shape of a rejected request: HTTP/1.1 429 Too Many Requests with a Retry-After header carrying a suggested wait in seconds, and a JSON body naming the error code TooManyRequests; Graph's own advice is to treat 429 as the detection signal, because "backing off requests using the Retry-After delay is the fastest way to recover from throttling"; where no Retry-After is returned, it recommends exponential backoff. For bulk operations, Graph's JSON batching reference states plainly that "JSON batch requests are currently limited to 20 individual requests," with each sub-request evaluated individually against throttling limits: throttled ones fail with 429 while "the batch itself succeeds with a status code of 200 (OK)".

Why it matters

Because @odata.nextLink already encodes provider-specific paging state (which can change between API versions or use a different mechanism per resource), any client that tries to parse or regenerate it instead of following it verbatim will break silently on the next Graph update. Batch requests do not share one throttling fate: one sub-request in a batch can be throttled while nineteen others succeed.

How to apply

• Follow @odata.nextLink as an opaque URL exactly as returned; do not extract or reconstruct its query parameters.
• Use $top to request a practical page size when an endpoint supports client-side paging, but always loop on @odata.nextLink rather than assuming a fixed number of pages.
• On 429, read Retry-After and wait that many seconds before any further request to the same or related endpoint; avoid immediate retries, which Graph's best practices explicitly discourage since "all requests accrue against your usage limits."
• Keep batches at or under 20 sub-requests, and check each sub-response's own status code — a batch-level 200 does not mean every sub-request succeeded.

Pitfalls

Building a "resume" mechanism that stores a parsed skipToken and tries to splice it into a new query later; Graph does not document its internal structure as stable. Retrying a throttled batch sub-request without isolating which of the up-to-20 items actually failed.