Do this with AI
Install the dx-cli and dx-delivery-sdk skills from Contentstack agent skills and connect the Delivery Analytics profile in MCP Profile Hub. Then ask your agent:
Show the API requests and 429 responses for my organization over the last 7 days, hour by hour, and point out the busiest hours. Then read my csdx import config and the content fetching code in lib/ and suggest a csdx config:set:rate-limit --utilize value and a concurrency limit that keep us under the limit. Don't run any import or publish.
New to this? Set up your AI workbench first.
Fix 429 rate limit errors in builds, imports and bulk publish
A 429 means Contentstack received more requests than your organization is allowed in that second. The request was fine. You sent too many at the same moment, usually from a static build, a csdx import, a bulk publish or a migration script.
This guide is about getting a failing job through: finding which limit you hit, backing off, pacing requests and restructuring the job. For cutting API calls on a running website, read Reducing API calls to boost performance and stay within rate limits.
What you'll learn
Which rate limit applies to which API, and why they are per organization
How to read the rate limit headers
What the SDKs and CLI already retry
How to back off, pace and cap concurrency in your own code
How to configure the CLI rate limit for imports and bulk publish
How to build static sites with fewer uncached requests
Symptoms
From the Delivery or Management SDK, or your logs:
{
error_message: 'Rate limit exceeded',
error_code: 429,
status: 429,
statusText: 'Too Many Requests'
}What you see around it:
HTTP 429 Too Many Requests from cdn.contentstack.io, api.contentstack.io or your region's equivalent
A static build that fails on a few random pages, more often right after a large publish
csdx cm:stacks:import or cm:stacks:export failing partway through a large stack
csdx cm:stacks:bulk-entries reporting failed items in its log folder
A migration or cleanup script that works on 50 entries and fails on 5,000
An Automate step that fails when many entries are saved at once
Why it happens
Each API has its own limit. These are the public defaults as of December 2026. All of them depend on your plan.
API | Default limit | What counts |
|---|---|---|
Content Delivery API (CDA) | 100 requests per second | Uncached requests only. Image Delivery API requests count too. Responses from the CDN cache don't. |
GraphQL Content Delivery API | 80 requests per second | Uncached requests only |
Content Management API (CMA) | 10 reads and 10 writes per second | Every request |
CMA bulk actions | 1 request per second | Each bulk publish request, which holds up to 10 items |
Contentstack concept: Rate limits are per organization, not per stack or per token. Your production build, a preview build, a teammate's import, an Automate workflow and a nightly script all draw from one budget. A job that works alone can fail when it overlaps with another.
The CDA limit only applies to requests that reach the origin. That is why 429s cluster after a publish. Publishing clears cached responses, so the next build sends most of its requests to the origin. The CDA documentation says it plainly: after publishing a large set of entries, a few requests can get a 429.
Static builds make it worse because they fan out. A site generator renders pages in parallel workers, and each page fetches its own entry, its references, the header, the footer and the navigation. A thousand pages can mean five thousand requests in under a minute.
Fix it
Read the headers first
Every rate-limited API returns two headers:
X-RateLimit-Limit: requests allowed per second for your organization
X-RateLimit-Remaining: requests left in the current window
Check your real limit with one Management API call:
curl -s -D - -o /dev/null \
-H "api_key: $CONTENTSTACK_API_KEY" \
-H "authorization: $CONTENTSTACK_MANAGEMENT_TOKEN" \
"https://api.contentstack.io/v3/content_types?limit=1" | grep -i x-ratelimitUse your region's host if you're not on AWS North America. The number you get is the one to plan against, not the defaults in the table above.
Let the SDKs retry
Both JavaScript SDKs retry 429s by default:
@contentstack/delivery-sdk retries up to 5 times. When a response says the window is used up, it waits for the reset time from the headers, otherwise 300 ms.
@contentstack/management retries up to 5 times, 300 ms apart, and sends at most 5 requests at a time (maxRequests).
If you see 429s surface from an SDK, the retries were not enough for the load. Lower the load before you raise retryLimit. For the Management SDK, maxRequests and delayMs slow the client down:
import contentstack from "@contentstack/management";
const client = contentstack.client({
maxRequests: 3, // concurrent requests
delayMs: 200, // wait before each request
retryLimit: 5,
});Back off in your own fetch code
Code that calls the REST API with fetch gets no retries for free. Back off exponentially, add jitter, and honor Retry-After when the response has one:
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
export async function fetchWithBackoff(
url: string,
init: RequestInit = {},
maxAttempts = 5
): Promise<Response> {
for (let attempt = 1; ; attempt++) {
const res = await fetch(url, init);
if (res.status !== 429 && res.status < 500) return res;
if (attempt >= maxAttempts) return res;
const retryAfter = Number(res.headers.get("retry-after"));
const backoff = Math.min(1000 * 2 ** (attempt - 1), 16_000);
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff + Math.random() * 250);
}
}The waits are 1, 2, 4 and 8 seconds plus jitter. Jitter matters when several workers hit the limit at once. Without it, they all retry in the same second and hit it again.
Pace scripts to a fixed rate
Retries handle bursts. A script that loops over thousands of entries needs a steady pace instead. Start a fixed number of requests per second and wait out the rest of each second:
export async function runPaced<T, R>(
items: T[],
perSecond: number,
fn: (item: T) => Promise<R>
): Promise<R[]> {
const results: R[] = [];
for (let i = 0; i < items.length; i += perSecond) {
const started = Date.now();
const batch = items.slice(i, i + perSecond);
results.push(...(await Promise.all(batch.map(fn))));
const elapsed = Date.now() - started;
if (elapsed < 1000) await sleep(1000 - elapsed);
}
return results;
}
// Half of a 10 requests per second write limit
await runPaced(entryUids, 5, (uid) => updateEntry(uid));Use about half of X-RateLimit-Limit. The other half is for everything else in your organization that runs at the same time.
Configure the CLI rate limit
csdx reads your organization's plan limits and uses a share of them. By default that share is 50%. Set it per organization:
# Use 50% of the plan limits (the default)
csdx config:set:rate-limit --org <org_uid>
# Use 30% of the bulk publish limit
csdx config:set:rate-limit --org <org_uid> --utilize 30 --limit-name bulkLimit
# Check what is set, or go back to the defaults
csdx config:get:rate-limit
csdx config:set:rate-limit --org <org_uid> --defaultThe limit names are getLimit (reads), limit (writes) and bulkLimit (bulk publish). The public docs state that rate limit configuration is supported for bulkLimit, which is what the bulk publish commands use. The setting is global for the organization on that machine, so lower it before a large job and reset it afterwards.
For imports and exports, the config file passed with --config accepts delayMs, which adds a pause before each API request:
{
"delayMs": 1000
}csdx cm:stacks:import --alias prod-import --data-dir ./export --config ./import-config.jsonLarge imports fail in other ways too, such as running out of memory. csdx import and export failures covers those.
Bulk publish without fighting the limit
Bulk publish has the tightest limit: 1 bulk request per second, 10 items per request. Publishing 1,000 entries through the API takes at least 100 requests. Work with that instead of around it:
Use the CLI's bulk mode. csdx cm:stacks:bulk-entries --operation publish --publish-mode bulk uses the Bulk Publish API and the CLI's bulkLimit pacing.
Retry only what failed. The command writes success and failure logs to ./bulk-operation. Rerun the failures with csdx cm:stacks:bulk-entries --retry-failed ./bulk-operation instead of the whole set.
Filter. --filter modified or --filter unpublished skips entries that are already published.
Don't run two at once. Only two bulk publish jobs are active at a time across an organization, so extra jobs wait their turn.
Use a release for coordinated changes. A release holds up to 500 items and deploys as one action. Releases, bulk publish and nested reference publishing explained covers when to pick which.
If publishing itself hangs instead of failing with a 429, read Publishing stuck or references not published.
Build static sites with fewer uncached requests
For builds, the fix is structural. Count the requests per page, then remove them:
Fetch lists, not entries. One query with limit() and only() that returns 100 entries replaces 100 single-entry requests. Paginate with skip().
Fetch shared data once. Header, footer, navigation and settings are the same on every page. Load them once per build.
Cap concurrency. Keep a fixed number of requests in flight. The worker pool in ETIMEDOUT, 5xx and timeouts from the Delivery API does this in 15 lines.
Use the Sync API for full builds. stack.sync({}, true) pages through every published entry and asset 100 items at a time. Store the result and the sync_token it returns. The next build asks only for what changed since then and merges it into the stored data.
Don't rebuild during a publish. Start the rebuild when the publish finishes, not on every entry publish event. Many publishes in a minute should lead to one build.
Prefer revalidation over full rebuilds. If your framework and host support it, revalidate the changed paths. The caching chapter shows how on Launch, and Revalidate, prime or redeploy helps you pick.
Automate workflows draw from the same organization budget. A workflow that triggers on every entry save and calls the Management API can collide with an import or a bulk publish. Trigger it on publish rather than save where you can, and schedule large automated jobs away from builds and imports.
Check that it worked
Run the job again and watch the headers. Log X-RateLimit-Remaining from a sample of responses. If it reaches 0 regularly, you are still at the limit and relying on retries.
For the CLI, check the failure log after a bulk run:
ls ./bulk-operationAn empty failure log means every item made it. In Analytics, the API usage for your organization should show the 429 count drop for the time window of the job.
Prevent it
Plan against X-RateLimit-Limit, not against the default numbers, and assume something else uses half of it.
Give every script a pace and every build a concurrency cap.
Schedule imports, bulk publishes and full rebuilds so they don't overlap. They share one organization budget.
Keep the CLI at 50% utilization or lower for long jobs.
Cache delivery responses where you can. Cached CDN responses aren't rate limited.
If your traffic legitimately outgrows the limit, ask Contentstack support about a higher limit for your plan.
See Contentstack limits on one page for the other limits that shape these jobs.
Key takeaways
A 429 means too many requests per second for your organization. Rate limits are shared by every stack, job and integration in it.
Default limits: CDA 100 uncached requests per second, GraphQL 80, CMA 10 reads and 10 writes, bulk actions 1. Your plan can change all of them.
The Delivery and Management SDKs retry 429s by default. Your own fetch code needs exponential backoff with jitter.
Pace scripts at about half of X-RateLimit-Limit.
Use csdx config:set:rate-limit --utilize and --retry-failed for large CLI jobs, and delayMs in import and export configs.
For builds, fetch lists instead of single entries, fetch shared data once, cap concurrency and use the Sync API.
Frequently asked questions
What are the default Contentstack API rate limits?
Uncached Content Delivery API requests are limited to 100 per second per organization, uncached GraphQL requests to 80, and the Management API to 10 reads and 10 writes per second. Bulk actions are limited to 1 request per second. All of these depend on your plan.
Are rate limits per stack or per organization?
Per organization. Every stack, build, script, CLI run and integration in the organization draws from the same budget.
Do cached Delivery API responses count against the rate limit?
No. Responses served from the CDN cache are not rate limited. They still count toward your overall API usage.
How do I slow down the Contentstack CLI?
Run csdx config:set:rate-limit with a lower --utilize percentage for your organization. The CLI then uses that share of your plan's limit.
Why do I get 429s right after a large publish?
Publishing clears cached responses, so the next requests go to the origin, which is rate limited. A build that starts right then sends far more uncached requests than usual.