Skip to main content
Contentstack MCP profile hub is in general availability!

Fix 429 rate limit errors in builds, imports and bulk publish

•
10 min read

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-ratelimit

Use 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> --default

The 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.json

Large 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-operation

An 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.