In a headless SitecoreAI implementation, front-end applications typically retrieve published content from Sitecore Experience Edge through the Experience Edge GraphQL API (the Delivery API). Experience Edge enforces several limits, including request rate limits, query complexity limits, and maximum page sizes.
This post covers each limit, how it shows up, and the GraphQL query optimization patterns that keep you under it. Every limit here comes from the official SitecoreAI documentation linked at the end, and the pagination query was tested on both the Preview and Delivery endpoints.
The limits at a glance
| Limit | Value |
|---|---|
| Delivery API rate limit | 80 uncached requests per second, 1-second reset window |
| Query complexity | A fixed score limit you can’t read |
Results per request (first) | Default 10, maximum 1000 |
Paths in includedPaths + excludedPaths | 100 path strings combined |
| Media item size | 50 MB |
| Sites per environment | 1000 |
Sources: Limitations and restrictions of Experience Edge, The Experience Edge schema.
1. Experience Edge rate limits
The Delivery GraphQL API allows 80 requests per second. Over that, Edge returns 429. Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-Rate-Limit-Limit | The limit (80) |
X-Rate-Limit-Remaining | Requests left in the current window (the 5th request in a second returns 75) |
X-Rate-Limit-Reset | Seconds until reset (1) |
The limit counts uncached requests. Sitecore’s Accelerate recipe warns it is easily reached if every visitor request queries Edge directly. Pages served from the host’s static cache don’t count against it.
Recommended practices:
- Serve pages statically: Generate at build time and revalidate on an interval instead of rendering every request on the server.
- Pre-build only the pages that matter: Use
includedPaths/excludedPathsfor the home page, top navigation and top-traffic pages. The rest generate on first request. - Throttle large builds: In
next.config.js,experimental.workerThreads: falseandcpus: 1cut concurrent Edge requests, at the cost of a longer build.
Configure retries. In the Sitecore Content SDK, every SitecoreClient method accepts a FetchOptions object with retries and retryStrategy. The default is 3 retries with an exponential back-off factor of 2. The default strategy retries 429, 502–504 and the Edge-specific 520–524, plus ECONNRESET, ETIMEDOUT and EPROTO.
// client is your app's SitecoreClient instance
const fetchOptions = {
retries: 2,
};
const page = await client.getPage(
'/about',
{ site: 'mysite', language: 'en' },
fetchOptions
);
Copy
2. GraphQL query complexity limits
Edge gives every query a numeric score based on how expensive it is to run, and rejects any query over the limit. The score itself cannot be retrieved, so the limit becomes visible only when a query is rejected.
Three characteristics affect how queries should be designed:
- Preview and Delivery score differently. Their data structures differ, so a query that passes on Preview can fail on Delivery. Test important queries against both endpoints, especially large ones.
- Only Preview is configurable. Preview settings live in
complexityConfigurationinsitecore.config, and you can raise them in non-production environments. Delivery’s cost can’t be configured, so the docs recommend simplifying queries instead of raising limits. firstand nestedchildrendrive cost. Thefirstargument feeds Preview’s calculation, and nestedchildrenfields onItemcan cause “Query is too complex to execute”.
<!-- Preview endpoint only, sitecore.config -->
<maxDepth>15</maxDepth> <!-- maximum nesting depth -->
<maxComplexity>10000</maxComplexity> <!-- maximum total field impact -->
<fieldImpact>2</fieldImpact> <!-- average impact of a list field -->
Copy
Reducing query complexity:
- Split big queries. Fetch a set of IDs or paths first, then query the details in follow-up queries. Large queries spanning many objects raise complexity sharply.
- Request only the fields you render. Remove anything the component doesn’t use.
- Replace deep
childrentrees with a filteredsearch. This is the author’s recommendation rather than official Sitecore guidance: one flat, paginated result list avoids the nested children pattern the docs flag. - Keep global data out of page queries. Fetch navigation and footer with their own query from the rendering host instead of embedding them in every page’s layout data. That also means a footer change republishes one query’s result, not every page.
Sources: The Experience Edge schema, Experience Edge best practices.
3. Cursor-based pagination in Sitecore GraphQL
Paginated fields such as search are cursor-based. first sets the page size (default 10, maximum 1000), and after takes the cursor to start from. Each response returns total, plus pageInfo.hasNext and pageInfo.endCursor.
To read more than one page, pass each response’s endCursor as the next request’s after, and stop when hasNext is false.
query ArticleList(
$rootPath: String!
$language: String!
$pageSize: Int!
$after: String
) {
search(
where: {
AND: [
{ name: "_path", value: $rootPath, operator: CONTAINS }
{ name: "_language", value: $language }
]
}
first: $pageSize
after: $after
) {
total
pageInfo {
endCursor
hasNext
}
results {
id
name
}
}
}
Copy
{
"rootPath": "<root item ID>",
"language": "en",
"pageSize": 2,
"after": null
}
Copy
For the next page, set after to the endCursor you just received. Every input is a variable, which also avoids the literal/variable bug in the next section. Keep pageSize modest: first feeds the complexity score on Preview.
Test results. The query was run against a data folder on both endpoints with a page size of 2:
| Preview | Delivery | |
|---|---|---|
total | 272 | 16 |
| Cursor format | Short (Mg==) | Long encoded string |
Page 2 via after | New items, new cursor | New items, new cursor |
- The
totaldiffers because Delivery returns only published content. Preview also counts unpublished items. - Treat
endCursoras opaque. Its format differs by endpoint, so pass it back asafterand never build or parse it. - The root item matches its own
_pathfilter. Exclude it in code if your listing shouldn’t show it.
Source: The Experience Edge schema.
4. Schema behaviour and common errors
Don’t mix literals and variables. Because of a known issue in the Edge schema, if a query uses any variable, every input must be a variable.
# Wrong: "true" is a literal next to a variable
search(where: {
AND: [
{ name: "_hasLayout", value: "true" }
{ name: "_parent", value: $parent }
]
})
# Right: every input is a variable
search(where: {
AND: [
{ name: "_hasLayout", value: $hasLayout }
{ name: "_parent", value: $parent }
]
})
Copy
Additional schema behaviour:
- Declared but missing variables fail. A
String!variable you don’t pass returns “Received a null input for a non-null field”. - Preview and Delivery need different tokens. A Preview API token doesn’t work on the Delivery endpoint. Get a Delivery token from the Deploy app.
searchfilters; it isn’t full-text search. For advanced search, the docs point to a dedicated search service.- Sorting or filtering on item text fields can be inconsistent, because the mirrored schema tokenizes differently.
- Persisted queries aren’t supported.
_latestversion: falsereturns an error on Delivery. Onlytrueis valid there.- Templates aren’t stored as items. An
itemquery for a template returnsnull. Query a published item’stemplate { id }instead. - Wildcard items resolve on Preview only, not on Delivery.
Caching and security practices:
- Pass dynamic values as variables, not string concatenation. The server can then reuse its parsed and validated query document.
- Give each query shape a stable, descriptive operation name. It improves cache hits and makes slow queries easy to find in logs.
- Keep your Context ID off the browser. Query from the server, or route client-side calls through an API route.
- Mark non-production sites as internal so the Delivery API doesn’t serve them.
Sources: Limitations and restrictions of Experience Edge, The Experience Edge schema, Experience Edge best practices.
In this way, developers can work more confidently with Experience Edge, keeping GraphQL queries efficient, content delivery reliable, and applications ready to scale.
References
- Limitations and restrictions of Experience Edge: rate limit, headers, capacity limits, literal/variable issue
- The Experience Edge schema: query complexity, pagination, schema restrictions
- Experience Edge best practices: Context ID, variables, operation names, global data
- Use retry strategies for requests to Experience Edge (Content SDK):
FetchOptions, default retry strategy - Working with Experience Edge rate limits and caching (Accelerate): caching and build optimisation