---
title: "Troubleshoot content delivery"
url: "https://developers.contentstack.com/paths/troubleshoot-content-delivery"
type: "path_full"
level: "intermediate"
outcome: "Delivery code that retries safely, stays within limits and returns the references and locales you expect."
steps:
  - "https://developers.contentstack.com/guides/etimedout-5xx-and-timeouts-from-the-delivery-api"
  - "https://developers.contentstack.com/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish"
  - "https://developers.contentstack.com/guides/nested-references-empty-or-error-141"
  - "https://developers.contentstack.com/guides/why-am-i-getting-en-us-content-locale-fallback-explained"
  - "https://developers.contentstack.com/guides/graphql-errors-decoded"
  - "https://developers.contentstack.com/guides/contentstack-limits-on-one-page"
updated: "2026-11-15T11:47:30.955Z"
---

# Troubleshoot content delivery

- **Level:** Intermediate
- **Steps:** 6
- **Overview:** https://developers.contentstack.com/paths/troubleshoot-content-delivery.md

---

Make Delivery API and GraphQL calls reliable. Handle timeouts and rate limits, fix empty references and unexpected locales, and know the limits before you hit them.

**You'll end up with:** Delivery code that retries safely, stays within limits and returns the references and locales you expect.

## Table of Contents

1. ETIMEDOUT, 5xx and timeouts from the Delivery API
2. Fix 429 rate limit errors in builds, imports and bulk publish
3. Nested references come back empty, or fail with error 141
4. Why am I getting en-us content? Locale fallback explained
5. GraphQL errors decoded: depth, cost and partial data
6. Contentstack limits on one page


---

## Step 1: ETIMEDOUT, 5xx and timeouts from the Delivery API

- **Source:** https://developers.contentstack.com/guides/etimedout-5xx-and-timeouts-from-the-delivery-api
- **Checkpoint:** Your fetch layer has timeouts, retries and keep-alive.

- **Authors:** Tim Benniks
- **Published:** 2026-12-07T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:55.217Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** api, sdk, headless

---

Your build dies halfway through prerendering with ETIMEDOUT, or a server-rendered page returns a 500 because a Delivery API call took too long. Run it again and it works. These failures are intermittent by nature, which makes them easy to ignore until they hit a release.

They show up most in static builds that fetch hundreds of pages at once, in server-rendered apps on Azure managed runtimes, and in any app that calls the API right after a large publish. The fix is the same in all three: fetch in a way that expects the network to fail now and then.

## What you'll learn

- How to read the error and tell a network failure from an API error


- What the TypeScript Delivery SDK already retries, and what it doesn't


- How to retry 5xx responses, set timeouts and cap concurrency


- How to fix SNAT port exhaustion on Azure with keep-alive and IPv4


- How to keep serving the last good content when a fetch fails



## Symptoms

From the TypeScript Delivery SDK (@contentstack/delivery-sdk):

```text
APIError: Request failed before a response was received (HTTP status 0).
  { error_code: 'ETIMEDOUT', status: 0 }
```

```text
Request timeout of 30000ms exceeded. Please try again or increase the timeout value in your configuration.
```

Other things you see:

- ETIMEDOUT, ECONNRESET, ECONNREFUSED, ENOTFOUND or EAI_AGAIN in Node.js logs


- UNKNOWN_ERROR with status: 0


- 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable or 504 Gateway Timeout from the CDA host


- Error occurred prerendering page "/blog/..." in a Next.js build, with one of the errors above as the cause


- CF005 on Launch, when a page's server function runs out of time while it waits on the API (see [Launch error codes decoded](/guides/launch-error-codes-decoded))



## Why it happens

The error tells you where to look. Sort it into one of three groups first.

What you see

What it means

Where to look

status: 0, ETIMEDOUT, ECONNRESET, ENOTFOUND

No HTTP response came back. The connection timed out, was reset, or DNS failed.

Your network path: outbound connection limits, DNS, too many sockets at once

502, 503, 504, 500 with a body

The request reached Contentstack and a server or gateway failed to answer.

[status.contentstack.com](https://status.contentstack.com), then your query cost

Request timeout of ...ms exceeded

A response was on its way but took longer than your client allowed.

Heavy queries (deep includes, large pages) and your timeout settings

Contentstack concept: The Content Delivery API sits behind a CDN. A cached response comes straight from the edge. An uncached one goes to the origin, which is slower and rate limited. A publish clears cached responses, so a build that starts right after a large publish sends far more traffic to the origin than the same build an hour later.

Status 0 errors are the most common, and they are usually not about Contentstack at all. A static build that renders 2,000 pages with 8 workers can open hundreds of TLS connections in a few seconds. On a laptop that's fine. On a serverless runtime or a container with limited outbound connections, new connections start to queue and time out.

Azure managed runtimes (App Service, Container Apps, Functions) are the clearest case. They share a pool of outbound SNAT ports across instances. Each new outbound TCP connection holds a port for a few minutes after it closes. Open connections fast enough and the pool runs dry, and new requests fail with ETIMEDOUT even though the API is healthy and has no record of them.

## Fix it

### Upgrade the SDK and know what it already does

Check what you run first:

```bash
npm ls @contentstack/delivery-sdk @contentstack/core
```

Since @contentstack/delivery-sdk 5.5.1 (with @contentstack/core 1.5.x), the SDK does this by default in Node.js:

- Timeout: 30,000 ms per request (timeout).


- Keep-alive: HTTP and HTTPS agents with keepAlive: true, so connections are reused.


- Retries: retryOnError is on, retryLimit is 5 and retryDelay is 300 ms.


- What it retries: 429 responses, and network errors with no response: ETIMEDOUT, ECONNRESET, ECONNREFUSED, ENOTFOUND, EAI_AGAIN, ENETUNREACH, EHOSTUNREACH and ENETDOWN. On a 429 it waits for Retry-After or the rate-limit reset header when the response has one.



What it does not do: retry 5xx responses, or back off exponentially. The delay between attempts is fixed. If you are on an older version, upgrade before you add anything else. Versions before 5.5.1 don't retry network errors by default and don't use keep-alive agents.

```bash
npm install @contentstack/delivery-sdk@latest
```

### Retry 5xx responses with jitter

Add a retryCondition for gateway errors. The SDK combines it with its built-in network check, so you only list what you want on top. customBackoff replaces the fixed delay. Use it to add jitter, so 8 build workers don't all retry in the same millisecond.

```typescript
import contentstack from "@contentstack/delivery-sdk";

const RETRYABLE_STATUS = [500, 502, 503, 504];

export const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
  region: process.env.CONTENTSTACK_REGION,
  timeout: 10_000,
  retryLimit: 3,
  retryCondition: (error) => RETRYABLE_STATUS.includes(error?.response?.status),
  retryDelayOptions: {
    // Used instead of the fixed delay: 0.5 to 1.5 seconds per attempt
    customBackoff: () => 500 + Math.floor(Math.random() * 1000),
  },
});
```

customBackoff gets no arguments, so it can't grow the delay per attempt. For true exponential backoff, wrap the call yourself (the [429 guide](/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish) has a helper). Don't retry other 4xx responses. A 412 or 422 means the request itself is wrong, and it will fail the same way every time.

### Set timeouts that fit your time budget

Retries multiply your timeout. With the defaults, one stuck request can take 30 seconds times 6 attempts. That is fine in a build. It is not fine inside a server function with its own limit. On Launch, a Cloud Function or SSR request times out after 30 seconds by default.

Use two configurations:

Where

timeout

retryLimit

Worst case

Static build or script

15,000 to 30,000 ms

3 to 5

Minutes, which a build can afford

SSR page or API route

5,000 ms

1 to 2

Under 20 seconds, inside the function limit

If a query regularly needs more than a few seconds, shorten the query instead of raising the timeout. Deep include_all_depth values and large reference trees are the usual cause. [Nested references empty or error 141](/guides/nested-references-empty-or-error-141) covers how to slim them down.

### Cap concurrency in builds

A static build that fires every page request at once is the most common source of ETIMEDOUT. Fetch the list once, then fetch details with a fixed number of requests in flight:

```typescript
export async function mapWithConcurrency<T, R>(
  items: T[],
  limit: number,
  fn: (item: T) => Promise<R>
): Promise<R[]> {
  const results: R[] = new Array(items.length);
  let next = 0;

  async function worker() {
    while (next < items.length) {
      const index = next++;
      results[index] = await fn(items[index]);
    }
  }

  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
  return results;
}

const { entries } = await stack.contentType("blogpost").entry().only(["uid", "url"]).query().find();

const posts = await mapWithConcurrency(entries ?? [], 5, (e) =>
  stack.contentType("blogpost").entry(e.uid).fetch()
);
```

Two more changes cut the connection count further:

- Fetch shared data once. Header, footer and navigation entries are the same on every page. Load them once per build and pass them down, instead of once per page.


- Fetch fewer, bigger pages. One list query that returns the fields every page needs replaces hundreds of single-entry calls. Use only() to keep the payload small.



### On Azure managed runtimes: keep-alive and IPv4

If your app runs on Azure App Service, Container Apps or Functions, including Launch projects on Azure, apply the two changes from the [Launch troubleshooting guide for Azure](https://www.contentstack.com/docs/launch/troubleshooting-guide-for-azure): reuse connections and resolve DNS to IPv4. Put both in one agent, so the IPv4 setting doesn't replace your keep-alive agent:

```typescript
import contentstack from "@contentstack/delivery-sdk";
import http from "node:http";
import https from "node:https";

const agentOptions = {
  keepAlive: true,
  keepAliveMsecs: 180_000,
  maxSockets: 50,
  maxFreeSockets: 20,
  family: 4, // resolve and connect over IPv4 only
};

export const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
  region: process.env.CONTENTSTACK_REGION,
  httpAgent: new http.Agent(agentOptions),
  httpsAgent: new https.Agent(agentOptions),
});
```

maxSockets is the important number. It caps how many connections the process opens to one host, and anything above it waits for a free socket instead of claiming a new SNAT port. The same pressure applies to every outbound call your app makes, so give your other HTTP clients a keep-alive agent too.

### Fail the build, or serve the last good data

When the API really is unavailable, you have two good options and one bad one. The bad one is shipping a build with empty pages because a fetch returned nothing.

Fail the build. On Launch and most hosts, a failed deployment doesn't replace the live one. For a fully static site, letting the build fail and retrying later is often the right call. Make sure errors propagate instead of being caught and turned into empty arrays.

Serve a snapshot. For data that rarely changes (navigation, settings, redirects), or for server-rendered routes where no previous build covers you, keep the last good response and fall back to it:

```typescript
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";

const SNAPSHOT_DIR = path.join(process.cwd(), ".content-snapshot");

export async function withSnapshot<T>(key: string, load: () => Promise<T>): Promise<T> {
  const file = path.join(SNAPSHOT_DIR, `${key}.json`);
  try {
    const data = await load();
    await mkdir(SNAPSHOT_DIR, { recursive: true });
    await writeFile(file, JSON.stringify(data));
    return data;
  } catch (error) {
    try {
      const cached = JSON.parse(await readFile(file, "utf8")) as T;
      console.warn(`[content] ${key}: serving snapshot after error`, error);
      return cached;
    } catch {
      throw error; // no snapshot yet: fail loudly
    }
  }
}

const nav = await withSnapshot("navigation", () =>
  stack.contentType("navigation").entry().query().find()
);
```

A file snapshot only survives between builds if your CI caches the directory. At runtime, an in-memory copy per server instance works the same way. For server-rendered pages on Launch, a Cache-Control header with stale-while-revalidate lets the CDN keep serving the last good page while the origin struggles. The [caching chapter](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming) shows the headers.

### Check the status page

Before you change code, open [status.contentstack.com](https://status.contentstack.com) and check your region for the time window of the errors. If there is an incident, retries and fallbacks are what carry you through it. If there isn't, and your errors are status 0, the cause is almost always on your side of the connection.

## Check that it worked

Measure a single request from the machine that fails. time_connect tells you how long the TCP connection took, which is where SNAT and DNS problems show up:

```bash
curl -sS -o /dev/null \
  -w "status=%{http_code} dns=%{time_namelookup}s connect=%{time_connect}s total=%{time_total}s\n" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  "https://cdn.contentstack.io/v3/content_types/blogpost/entries?environment=production&limit=1"
```

Use your region's CDA host if you are not on AWS North America. A connect time of several seconds, or a timeout here while the same request is fast from your laptop, points at the network path.

Then log what the SDK does. Pass a logHandler with debug: true and count failed attempts in a build:

```typescript
export const stack = contentstack.stack({
  // ...credentials and retry settings
  debug: true,
  logHandler: (level, data) => {
    if (data?.type === "response_error") {
      console.warn(`[cda] ${data.status} ${data.method} ${data.url} ${data.error}`);
    }
  },
});
```

After the fixes, a build should show a few retried errors at most, and no failed pages. In Analytics, the Delivery API status codes for your organization should show the 5xx and 429 counts drop.

## Prevent it

- Keep @contentstack/delivery-sdk current. Retry and keep-alive behavior improved a lot during 5.x.


- Give every build a concurrency cap, and fetch shared entries once.


- Keep SSR timeouts and retry counts below your hosting function's own limit.


- Don't start a full rebuild in the same minute as a large bulk publish. Let the publish finish first, or prime the pages you need most.


- Load test with the hosting provider in the loop. On Launch, coordinate load tests with Contentstack first, as the [Launch load testing docs](https://www.contentstack.com/docs/developers/launch/load-testing) describe.


- If the errors are 429s rather than timeouts, read [Fix 429 rate limit errors in builds, imports and bulk publish](/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish). The limits that apply are listed in [Contentstack limits on one page](/guides/contentstack-limits-on-one-page).



## Key takeaways

- status: 0 and ETIMEDOUT mean no response came back. Look at your network path and concurrency before you look at Contentstack.


- The Delivery SDK retries 429s and network errors 5 times by default, 300 ms apart. Add a retryCondition for 500, 502, 503 and 504.


- Keep timeout times retryLimit inside the time budget of where the code runs: long in builds, short in SSR.


- Cap concurrent requests in builds with a small worker pool, and fetch shared data once.


- On Azure managed runtimes, use one keep-alive agent with maxSockets and family: 4.


- Decide up front whether a failed fetch fails the build or serves the last good data. Never ship empty pages.


- Check [status.contentstack.com](https://status.contentstack.com) before you change code.





---

## Do this with AI

Install the dx-delivery-sdk skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Delivery Analytics profile in MCP Profile Hub. Then ask your agent:

> Show the Content Delivery API status codes for my organization over the last 7 days, hour by hour, and list the hours with the most 5xx or 429 responses. Then read lib/contentstack.ts and tell me which timeout, retryLimit and retryCondition settings my stack() call uses and what you would change for a static build.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### What is the default timeout of the TypeScript Delivery SDK?

30 seconds per request. Set the timeout option on contentstack.stack() to change it.

### Does the Delivery SDK retry failed requests?

Yes. Current versions retry 429 responses and network errors such as ETIMEDOUT, ECONNRESET and ENOTFOUND up to 5 times, 300 ms apart. They do not retry 5xx responses unless you add a retryCondition.

### What does "Request failed before a response was received (HTTP status 0)" mean?

The request never got an HTTP response. The connection timed out, was reset or could not be opened, so the cause is on the network path between your server and the API, not in your query.

### Why do I only see ETIMEDOUT on Azure?

Azure managed runtimes share a limited pool of outbound SNAT ports. Under many concurrent new connections the pool runs out and new connections time out. Keep-alive and IPv4 resolution fix most of it.

### Where do I check whether Contentstack has an incident?

On status.contentstack.com. If it shows no incident for your region and time window, look at your own network path and concurrency first.


---

## Step 2: Fix 429 rate limit errors in builds, imports and bulk publish

- **Source:** https://developers.contentstack.com/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish
- **Checkpoint:** Builds and imports back off instead of failing on 429.

- **Authors:** Tim Benniks
- **Published:** 2026-12-08T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:56.807Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** api, cli, automation

---

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](/guides/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:

```text
{
  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:

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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:

```bash
# 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:

```json
{
  "delayMs": 1000
}
```

```bash
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](/guides/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](/blog/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](/guides/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](/guides/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](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming) shows how on Launch, and [Revalidate, prime or redeploy](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch) 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:

```bash
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](/guides/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.





---

## Do this with AI

Install the dx-cli and dx-delivery-sdk skills from [Contentstack agent skills](https://github.com/contentstack/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](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

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


---

## Step 3: Nested references come back empty, or fail with error 141

- **Source:** https://developers.contentstack.com/guides/nested-references-empty-or-error-141
- **Checkpoint:** Deep references resolve or are modeled around the depth limit.

- **Authors:** Tim Benniks
- **Published:** 2026-12-09T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:10.772Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** api, sdk, content_modeling

---

A page renders without its author, a card list is empty, or the whole request fails with 422 and error_code: 141. The entry is there in the CMS, the references are filled in, and the response still does not contain them.

This usually happens on pages built from modular blocks, global fields and references, fetched with the TypeScript Delivery SDK or the Content Delivery API (CDA) from a server, a static build or a Live Preview session. The causes are few, and each leaves a different trace in the response.

## What you'll learn

- How to recognize each cause from what the response looks like


- How to write include[] paths that match your schema, including blocks and global fields


- Where the depth and include limits are, and what happens when you cross them


- How publish state and locale affect resolved references


- How to model content so pages do not need deep reference chains



## Symptoms

What you see

Likely cause

The reference field holds [{ "uid": "blt...", "_content_type_uid": "author" }]

The path was not included

The field is resolved at level one, but nested references are still bare UIDs

include_all without a depth, or a nested path missing from include[]

A multiple reference field returns fewer items than the editor selected

Some referenced entries are not published to that environment or locale

A reference inside a modular block or global field is never resolved

The include path skips a block UID or uses the wrong global field UID

422 with "error_code": 141 and "Failed to fetch entries. Please try again with valid parameters."

The API rejected a parameter, for example a depth or include count over the limit

422 with "error_code": 141 and "The requested object doesn't exist."

The entry you fetched by UID is not published in that environment and locale

414 URI Too Long

Too many or too long include paths in the URL

## Why it happens

Contentstack concept: A Reference field stores pairs of uid and _content_type_uid. The referenced entry is a separate entry with its own versions, its own localized copies and its own publish state per environment and locale.

Three things follow from that.

First, references are lazy. The CDA returns the stored pairs unless you ask it to resolve a path with include[]. Nothing is resolved by default, and a nested reference is only resolved when its full path is included too.

Second, the CDA resolves a reference from what is published. If the referenced entry is not published to the environment and locale you query, there is nothing to inline, and it drops out of the result.

Third, resolution is bounded. Each included level multiplies the entries the CDA has to fetch, so the API caps the number of paths and the depth. Requests that go past those caps fail instead of returning partial data.

If you come from SQL, think of include[] as an explicit join list. There is no lazy loading on access, and the joins you do not name are not made.

## Fix it

### The path is not included

Include every path the page renders. With the TypeScript Delivery SDK, call includeReference() before you build the query. Nested references use dot notation, and each level needs its own path:

```typescript
import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

const result = await stack
  .contentType("blogpost")
  .entry()
  .includeReference("author", "author.company", "related_posts")
  .query()
  .where("url", QueryOperation.EQUALS, "/blog/hello-world")
  .find();
```

author.company resolves the company referenced from the author. Without it, author is resolved and author.company stays a bare UID.

The same request with curl:

```bash
curl -G "https://cdn.contentstack.io/v3/content_types/blogpost/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode "include[]=author" \
  --data-urlencode "include[]=author.company" \
  --data-urlencode "include[]=related_posts"
```

Use your region's CDA host if your stack is not in AWS North America.

If a reference field allows more than one content type, also call includeReferenceContentTypeUID(). Each resolved entry then carries its _content_type_uid, so your renderer knows which component to use.

### References inside modular blocks, groups and global fields

Paths follow the schema, not the rendered shape. For a reference inside a block, the path is the modular blocks field UID, then the block UID, then the reference field UID:

```typescript
const page = await stack
  .contentType("landing_page")
  .entry()
  .includeReference(
    "sections.testimonial.person",
    "sections.card_grid.cards",
    "sections.card_grid.cards.author"
  )
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();
```

Groups work the same way: group_uid.reference_uid.

Global fields are where most paths go wrong. A global field behaves like a group, and the path uses the UID the global field has on this content type, not the UID of the global field itself. If the seo global field is added to landing_page as page_seo, and it contains a reference og_author, the path is page_seo.og_author. Inside a block, it becomes sections.hero.page_seo.og_author.

Fetch the content type's schema from GET /v3/content_types/landing_page on the CDA and read the uid values from the top down. That is your path. A path that does not match resolves nothing, or fails the request.

### The referenced entry is not published

Publishing a blog post does not publish its author. If the author is unpublished, or published to staging but not production, or published in en-us but not de-de, it is missing from the resolved response.

Fix it at the source:

- Publish the referenced entries to the same environment and locale. In the publish dialog, editors can include references, and nested reference publishing sends them up to five levels deep.


- For locales, check whether the referenced entry is published in the locale you request. If you rely on fallback, pass include_fallback=true (see [Why am I getting en-us content?](/guides/why-am-i-getting-en-us-content-locale-fallback-explained)).



In code, treat a resolved reference as optional. A field that is required in the CMS can still be missing in the delivered JSON:

```typescript
type Author = { uid: string; title: string; url?: string };

function authorsOf(entry: { author?: Author[] }) {
  return (entry.author ?? []).filter((a): a is Author => Boolean(a?.title));
}
```

The filter drops stubs that only have a uid, so one missing author does not break the page. The [publishing explainer](/blog/releases-bulk-publish-and-nested-reference-publishing-explained) covers releases, bulk publish and nested reference publishing, and [Publishing stuck or references not published](/guides/publishing-stuck-or-references-not-published) covers the publish side of this problem.

### include_all without a depth

include_all=true resolves every reference field on the entry, but only one level deep. Nested references stay as UIDs. Add include_all_depth to go further:

```typescript
const page = await stack
  .contentType("landing_page")
  .entry()
  .addParams({ include_all: true, include_all_depth: 2 })
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();
```

The maximum depth is 5. A higher value returns an error. Use include_all for prototypes and preview tooling. For production pages, list the paths. It is easier to reason about and fetches less.

### Too deep or too many includes: 422 with error_code 141

The CDA rejects a request it will not resolve, with 422, error_code: 141 and the message Failed to fetch entries. Please try again with valid parameters. The errors object in the body usually names the parameter. The limits to check:

Limit

Value

Reference paths per request (include[] or include_all)

100

include_all_depth

1 by default, 5 at most

Multiple content type Reference fields

resolve up to 3 levels deep

Request URL size on the CDN

8 KB, above that 414 URI Too Long

Paths count per path, not per entry. sections.card_grid.cards and sections.card_grid.cards.author are two paths. A page with ten block types and three levels each reaches 100 quickly.

When you hit one of these, split the request. Fetch the page with the first levels, collect the UIDs of the deep references, and fetch those in a second query:

```typescript
const [page] = (await stack
  .contentType("landing_page")
  .entry()
  .includeReference("sections.card_grid.cards")
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find()).entries ?? [];

const authorUids = (page?.sections ?? [])
  .flatMap((s: any) => s.card_grid?.cards ?? [])
  .flatMap((card: any) => card.author ?? [])
  .map((ref: { uid: string }) => ref.uid);

const authors = authorUids.length
  ? (await stack
      .contentType("author")
      .entry()
      .query()
      .containedIn("uid", [...new Set(authorUids)])
      .find()).entries ?? []
  : [];
```

Two small requests are cheaper and easier to cache than one request at the edge of every limit.

### Error 141 that has nothing to do with references

141 is a generic code. Before you rewrite include paths, rule out the other causes:

- The requested object doesn't exist. on a single-entry fetch means that entry is not published in that environment and locale, or the UID belongs to another content type.


- An environment or locale the delivery token cannot read also returns 422 with 141. Check that the token is scoped to the environment, and that the locale code exists in the stack in lowercase.


- A malformed query parameter returns the same Failed to fetch entries message.



Strip the request down to environment only. If that works, add parameters back one by one until it fails.

## Check that it worked

Run the request with curl and inspect the reference field:

```bash
curl -sG "https://cdn.contentstack.io/v3/content_types/landing_page/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"url":"/pricing"}' \
  --data-urlencode "include[]=sections.card_grid.cards" \
  | jq '.entries[0].sections[] | .card_grid.cards[]? | {uid, title}'
```

Every card should have a title. A card with only uid is either a path you did not include or an entry that is not published. Compare the count with the editor's selection to spot unpublished entries.

## Prevent it

- Keep include paths next to the component that renders them, and build the list for a page from the components it uses. A new block then brings its own paths.


- Type resolved references as optional in your code. The CMS can require a reference that the delivery response leaves out.


- Teach editors to publish with references, or bundle pages and their references in a release.


- Keep reference chains short. A page that references sections, which reference cards, which reference authors, is three levels deep before it renders. Most of those levels can be modular blocks or global fields, which come back with the entry for free. [Modular blocks, references or global fields?](/guides/modular-blocks-references-or-global-fields) walks through that decision with examples.


- Watch the URL length when you build paths programmatically. A long list of includes is the most common source of 414.



## Key takeaways

- References are not resolved unless you include the full dot-notation path, one path per level.


- Paths follow the schema: blocks field UID, block UID, the global field's UID on this content type, then the reference field UID.


- A referenced entry that is not published in that environment and locale drops out of the response.


- include_all stops at depth 1 unless you set include_all_depth, which goes up to 5. A request resolves at most 100 paths.


- 422 with error_code: 141 is generic. Read the message and the errors object before you change anything.


- Split deep pages into two queries, and model shared content as blocks or global fields when it does not need its own lifecycle.



## Next steps

- Read [Modular blocks, references or global fields?](/guides/modular-blocks-references-or-global-fields) before you add another reference level.


- If you query with GraphQL, see [GraphQL errors decoded](/guides/graphql-errors-decoded) for the depth and cost limits there.


- Keep [Contentstack limits on one page](/guides/contentstack-limits-on-one-page) open while you design queries.





---

## Do this with AI

Install the cms-data-modeling-best-practices and dx-delivery-sdk skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Broken Reference Checker profile in MCP Profile Hub. Then ask your agent:

> Check the published landing_page entries in production for references that point to unpublished or deleted entries, list the include paths my page query needs for every reference field in that content type, and flag any path deeper than three levels.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Why does my reference field only contain uid and _content_type_uid?

References are not resolved unless you ask for them. Add the field path to include[] or call includeReference() with the full dot-notation path.

### Why is a referenced entry missing from the array even though it exists?

The referenced entry is not published to that environment and locale. The parent's publish does not publish its references.

### How deep can include_all go?

include_all resolves one level by default. include_all_depth raises that up to 5, and a request resolves at most 100 reference paths whatever the depth.

### What does error_code 141 mean on the Content Delivery API?

It is a generic 422 code. It covers missing entries, an environment or locale the token cannot read, and request parameters the API rejects, so read the error message and errors object, not just the code.

### How do I include a reference that sits in a global field inside a modular block?

Use the full path from the content type, starting with the modular blocks field UID, block UID, the global field's UID on that content type, then the reference field UID.


---

## Step 4: Why am I getting en-us content? Locale fallback explained

- **Source:** https://developers.contentstack.com/guides/why-am-i-getting-en-us-content-locale-fallback-explained
- **Checkpoint:** Locale fallback behaves the way you configured it.

- **Authors:** Tim Benniks
- **Published:** 2026-12-10T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:30.328Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** i18n, api

---

You request locale=de-de, the response is a 200, and the text is English. Or your German page shows a German title with an English image caption and English author bio. Nothing errors, and nothing tells you which part came from where.

This hits every multi-language site at some point, whatever the framework: Next.js with i18n routing, Nuxt, Astro, or a static build that loops over locales. The cause is almost never a bug. It is one of a handful of localization rules doing exactly what they are designed to do.

## What you'll learn

- How fallback languages, localized and unlocalized entries relate


- Why publishing an unlocalized entry serves fallback content under the new locale


- What include_fallback and GraphQL fallback_locale change, and what they do not


- How to read a response to see which locale the content came from


- How locale codes, non-localizable fields, references and variants add to the confusion



## Symptoms

What you see

Likely cause

locale=de-de returns master language text with a 200

The entry was published in de-de without being localized

A German page mixes German and English fields

Non-localizable fields, or English referenced entries

Entries appear in de-de only when you add include_fallback=true

They are not published in de-de. Fallback fills the gap

GraphQL with fallback_locale: false still returns English

Same as the first row. The content is published in that locale

422 with error_code: 141 for a locale

The locale code does not exist in the stack, or the token cannot read it

GraphQL INVALID_LOCALE: "The queried locale 'en-uk' is invalid."

The locale code does not exist in the stack

A personalized variant shows base content in one language only

The variant has no content for that locale

## Why it happens

Contentstack concept: Every stack has one master language, set when the stack is created. Every other language has a fallback language. An entry exists in the master language and can have a localized version per language. Until you localize it, the entry in that language is unlocalized and inherits its content from the fallback language.

Inheritance follows the chain. If de-at falls back to de-de, and the entry has no de-de content, it inherits from the master. The chain is short on purpose: a non-master language can fall back to another language, and a language that is already a fallback can only fall back to the master. So the longest chain looks like de-at → de-de → en-us.

The part that surprises most developers is publishing. When an editor publishes an unlocalized entry in de-de, Contentstack publishes the latest content from its fallback language under de-de. The Content Delivery API (CDA) now has a real de-de document for that entry, and it holds English text. Your request for de-de returns it, with or without fallback flags.

If you come from i18n libraries, this is closer to "copy the default translation into the bundle at build time" than to "fall back at runtime when a key is missing".

There is a second, separate mechanism at delivery time. When an entry is not published in the requested locale at all, the CDA leaves it out of the response. With include_fallback=true, it returns the version published in the fallback language instead. That fallback version must itself be published.

flowchart TD  A[Request locale=de-de] --> B{Entry published in de-de?}  B -- Yes --> C{Localized in de-de?}  C -- Yes --> D[German content]  C -- No --> E[Fallback content, published under de-de]  B -- No --> F{include_fallback=true?}  F -- No --> G[Entry left out, or 422 for a single entry]  F -- Yes --> H[Version published in the fallback language]## Fix it

### Find out which case you are in

Fetch the entry and look at two fields: the entry's locale and publish_details.

```bash
curl -sG "https://cdn.contentstack.io/v3/content_types/product/entries/$ENTRY_UID" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode "locale=de-de" \
  | jq '.entry | {title, locale, publish_details}'
```

locale tells you which language the content belongs to. publish_details.locale tells you which locale it was published in. An unlocalized entry published in de-de typically shows locale: "en-us" with publish_details.locale: "de-de". A localized entry shows de-de in both.

In GraphQL, ask for the same data through system:

```graphql
query {
  product(uid: "blt0123456789abcdef", locale: "de-de") {
    title
    system {
      locale
      publish_details {
        locale
      }
    }
  }
}
```

### The entry was published without being localized

This is the most common case, and the fix is editorial. Open the entry, switch to de-de, localize it, translate the fields, and publish it in de-de again. From then on, de-de has its own content and stops inheriting.

If the English content should not be live in German at all, unpublish the entry from de-de until the translation is ready. A request for de-de then leaves it out, unless you ask for fallback.

To find all of them, compare locale against the requested locale across a listing:

```typescript
import contentstack from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

const requested = "de-de";

const { entries = [] } = await stack
  .contentType("product")
  .entry()
  .locale(requested)
  .only(["title", "locale"])
  .find<{ uid: string; title: string; locale: string }>();

const notTranslated = entries.filter((e) => e.locale !== requested);
console.table(notTranslated.map(({ uid, title, locale }) => ({ uid, title, locale })));
```

Run it for each locale before a release. It turns "some pages look English" into a list of entry UIDs an editor can work through.

### You asked for fallback

If your code sets include_fallback=true, English content for missing translations is the expected result. With the SDK:

```typescript
const result = await stack
  .contentType("product")
  .entry()
  .locale("de-de")
  .includeFallback()
  .find();
```

In GraphQL, the equivalent is the fallback_locale argument:

```graphql
query {
  all_product(locale: "de-de", fallback_locale: true) {
    items {
      title
      system {
        locale
      }
    }
  }
}
```

Decide per page whether fallback is what you want. A product listing usually wants every product, in German where it exists and in the fallback language where it does not. A legal page usually wants German or nothing. Keep fallback off where a mix of languages would be wrong, and handle the missing entry in code.

Turning fallback off does not hide entries that were published unlocalized in de-de. Those are real de-de documents. That is why fallback_locale: false can still return English.

### The locale code is wrong

Stack locale codes are lowercase, like en-us, de-de and fr-ca. Frameworks often use de-DE. Do not pass the framework value straight through. Map it:

```typescript
const toStackLocale = (routeLocale: string) => routeLocale.toLowerCase();

const entries = await stack
  .contentType("page")
  .entry()
  .locale(toStackLocale(params.locale))
  .find();
```

A locale that is not in the stack returns 422 with error_code: 141 on the CDA and INVALID_LOCALE in GraphQL. If your routes use codes that differ from the stack's, such as de for de-de, keep an explicit map instead of string manipulation. The [multi-language Next.js guide](/guides/building-a-multi-language-website-using-contentstack-and-next-js-i18n) shows the full routing setup.

### Non-localizable fields always show the master value

A field marked non-localizable is edited in the master language only. Its value is copied to every localized version, and in localized entries it is read-only. An English image caption on a German page often comes from this setting.

When an editor changes that field in the master language, the localized versions update automatically and get a new version number. Published localized versions do not change until they are published again, so publish the affected locales after a change to a non-localizable field.

If the field needs per-language values, make it localizable in the content type. Group, modular block and global field instances that an editor adds in a localized entry are an exception: those instances can be edited there.

### Referenced entries have their own locales

A German page can reference an author entry that only exists in English. Each referenced entry is localized and published on its own. Resolving the reference returns whatever that entry has in the requested locale, which can be an unlocalized English copy published under de-de. Run the check above on referenced content types too. If a reference disappears instead, see [Nested references come back empty](/guides/nested-references-empty-or-error-141).

### Personalized variants

Entry variants are stored per locale. If a variant has no content in the requested locale, you get the base entry for that locale. [Personalize variant returns the base entry or null](/guides/personalize-variant-returns-base-entry-or-null) covers that case in depth.

## Check that it worked

- Rerun the curl request. locale and publish_details.locale should both match the locale you requested.


- Rerun the listing script. notTranslated should be empty, or only contain entries you chose to leave in the fallback language.


- If your site caches pages, purge or revalidate the affected locale paths. Each locale is cached separately, so republishing de-de does not refresh en-us pages and the other way around.



## Prevent it

- Add the listing check to CI or a scheduled job per locale, and fail or warn when a page-level content type has unlocalized entries in a non-master locale.


- Agree on a rule with editors: publish in a new locale only after localizing, or use a workflow stage for translation before publish.


- Decide where fallback is allowed and set include_fallback per query, not globally.


- Keep fields that are truly shared, like SKUs and dates, non-localizable. Make every field a reader sees localizable.


- Normalize locale codes in one function and use it in routing, data fetching and cache keys.



## Key takeaways

- An unlocalized entry inherits content from its fallback language. Publishing it in a locale publishes that inherited content under the locale.


- include_fallback=true and fallback_locale: true only matter when an entry is not published in the requested locale.


- Compare locale with publish_details.locale to see whether content was translated or inherited.


- Fallback chains are one level deep for non-master languages: de-at → de-de → en-us is as long as it gets.


- Stack locale codes are lowercase. Map framework codes before you query.


- Non-localizable fields always carry the master value. Republish localized entries after you change one.



## Next steps

- Follow the [multi-language Next.js guide](/guides/building-a-multi-language-website-using-contentstack-and-next-js-i18n) to wire locales into routing.


- If localized pages stay stale after publishing, read [Published, but my site still shows old content](/guides/published-but-my-site-still-shows-old-content).


- Check [Contentstack limits on one page](/guides/contentstack-limits-on-one-page) for language and fallback limits.





---

## Do this with AI

Install the cms-localization skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Localization Gap Finder profile in MCP Profile Hub. Then ask your agent:

> List the product entries that are published to production in de-de but not localized in de-de, so they serve fallback content, and sort them by last update so I know which to translate first.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Why does the API return English text when I request de-de?

Usually the entry was published in de-de without being localized, so the English content from its fallback language was published under de-de. The API returns it like any other de-de entry.

### What does include_fallback do?

When an entry is not published in the requested locale, include_fallback=true returns the version published in its fallback language instead of leaving it out.

### How deep can a fallback chain go?

One level for non-master languages. A language can fall back to another language, and that language can only fall back to the master language.

### Are locale codes case-sensitive?

Treat them as such. Stack locale codes are lowercase, like de-de, so map de-DE from your framework to de-de before you call the API.

### Why does a non-localizable field show the master value in every locale?

That is what non-localizable means. The field is edited only in the master language and its value is copied to every localized version.


---

## Step 5: GraphQL errors decoded: depth, cost and partial data

- **Source:** https://developers.contentstack.com/guides/graphql-errors-decoded
- **Checkpoint:** You can read and fix GraphQL limit and partial-data errors.

- **Authors:** Tim Benniks
- **Published:** 2026-12-11T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:59.938Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** api, graphql

---

Contentstack's GraphQL Content Delivery API fails in two different ways. Some queries are rejected before they run, with a 422 and a code like MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED. Others run, return HTTP 200, and quietly leave holes in data that are only explained in errors.

If you use Apollo, urql, graphql-request or a plain fetch from Next.js, Nuxt or Astro, both show up the same way at first: a page that renders with missing content, or a build that fails on one route. This guide decodes the errors you are most likely to see and shows how to rewrite the query for each.

## What you'll learn

- How to tell a rejected query from a partial result


- What the depth, cost, document and page size limits are


- How to rewrite queries that go too deep or fetch too much


- Why the default page size is 25 and how to paginate past it


- Which schema, type and branch quirks look like errors but are not



## Symptoms

Code or symptom

HTTP

Example message

MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED

422

Max allowed nested reference depth limit is '3', but the query has '5' nested references.

MAX_RESOLVER_COST_EXCEEDED

422

Max allowed cost per query is 20. Resolver cost calculated was 21.

MAX_DOCUMENT_LIMIT_EXCEEDED

422

Maximum allowed documents in a single query are '7500', but the query has requested '9234' documents.

MAX_ROOT_FETCH_LIMIT_EXCEEDED

422

Max allowed limit to fetch a content types is '100'.

MAX_REFERENCE_LIMIT_EXCEEDED

422

Max allowed limit per reference for your organization is '100', but the query requested '120'.

MAX_QUERIED_CONTENT_TYPE_LIMIT_EXCEEDED

422

Maximum allowed content types queried at a time is 'THREE'

INVALID_BRANCH

422

The queried branch 'develop' is invalid.

INVALID_LOCALE

422

The queried locale 'en-uk' is invalid.

SCHEMA_BUILD_ERROR

422

Unable to generate GraphQL types. Check details for more info.

RESPONSE_SIZE_TOO_BIG

503

Maximum response size allowed is 7 MB.

SERVICE_UNAVAILABLE

504

Request timeout!

errors[] next to data, some fields null

200

Failed to run query.

A list stops at 25 items

200

No error

## Why it happens

Contentstack concept: The GraphQL API generates its schema from your content types on each request, and it checks every query against plan-based limits on documents, resolver cost, content types and reference depth before it runs.

That gives you two classes of errors.

Rejected before execution. The API reads the query, works out how deep it goes, how many entries it could fetch and how many database calls it needs, and compares that with the limits. If the query is over, nothing runs and you get a non-2xx status. The body has the code in extensions.errors:

```json
{
  "errors": [
    {
      "message": "Failed to run query.",
      "extensions": {
        "errors": [
          {
            "code": "MAX_ROOT_FETCH_LIMIT_EXCEEDED",
            "message": "Max allowed limit to fetch a content types is '100'.",
            "details": { "hint": "The 'all_product' argument can fetch maximum '100' content types." }
          }
        ]
      }
    }
  ]
}
```

Failed during execution. The query is valid and ran, but a field could not be resolved. A referenced entry is missing, or a resolver ran out of budget. You get HTTP 200, data with that field set to null, and an entry in errors with a path pointing at the field:

```json
{
  "data": {
    "all_article": { "items": [{ "title": "Hello", "author": null }] }
  },
  "errors": [
    {
      "message": "Failed to run query.",
      "path": ["all_article", "items", 0, "author"],
      "extensions": { "errors": [{ "code": "...", "message": "...", "details": { "hint": "..." } }] }
    }
  ]
}
```

The status code describes the transport. The body describes the operation. A client that only checks response.ok renders the hole.

## Fix it

### Always read errors, even on 200

Start here, because it makes every other error visible. A small wrapper around fetch is enough:

```typescript
const GRAPHQL_HOST = process.env.CONTENTSTACK_GRAPHQL_HOST ?? "https://graphql.contentstack.com";

type GqlError = {
  message: string;
  path?: (string | number)[];
  extensions?: { errors?: { code: string; message: string; details?: { hint?: string } }[] };
};

export async function gql<T>(query: string, variables: Record<string, unknown> = {}) {
  const url = `${GRAPHQL_HOST}/stacks/${process.env.CONTENTSTACK_API_KEY}?environment=${process.env.CONTENTSTACK_ENVIRONMENT}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      access_token: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
    },
    body: JSON.stringify({ query, variables }),
  });

  const body = (await response.json()) as { data?: T; errors?: GqlError[] };

  const details = (body.errors ?? []).map((e) => {
    const inner = e.extensions?.errors?.[0];
    return `${inner?.code ?? "ERROR"} at ${e.path?.join(".") ?? "query"}: ${inner?.message ?? e.message}`;
  });

  if (!response.ok) {
    throw new Error(`GraphQL ${response.status}: ${details.join("; ")}`);
  }

  if (details.length > 0) {
    console.warn(`GraphQL partial result: ${details.join("; ")}`);
  }

  return body.data as T;
}
```

Throw on non-2xx. For partial results, decide per route: a build should usually fail, a server-rendered page can log and render what it has. Use your region's GraphQL host if your stack is not in AWS North America.

### MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED

Nested references can be fetched up to three levels deep. This query is four levels: page, section, card, author, company.

```graphql
query {
  page(uid: "blt0123456789abcdef") {
    sectionsConnection {
      edges {
        node {
          ... on Section {
            cardsConnection {
              edges {
                node {
                  ... on Card {
                    authorConnection {
                      edges {
                        node {
                          ... on Author {
                            companyConnection { edges { node { ... on Company { title } } } }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

There is no flag to raise the limit for a single query. You have three options, in this order:

- Stop at the last level you need. Fetch author { system { uid } } at level three and resolve the company in a second query by UID.


- Split the query by subtree. Fetch the page and its sections in one query and the cards with their authors in another. Two small queries cache better than one large one.


- Change the model. Most deep chains come from modeling sections and cards as separate entries when they could be modular blocks or global fields, which come back with the entry and do not count as reference levels. [Modular blocks, references or global fields?](/guides/modular-blocks-references-or-global-fields) covers the trade-off.



Reference filters in where have the same three-level limit. A filter that goes deeper fails with REF_FILTER_DEPTH_EXCEEDED.

### MAX_RESOLVER_COST_EXCEEDED and MAX_DOCUMENT_LIMIT_EXCEEDED

Two numbers decide whether a query is too big:

- Complexity is the number of entries the query could fetch. The maximum is 7,500 documents per query. Over that, you get MAX_DOCUMENT_LIMIT_EXCEEDED.


- Resolver cost is the number of database calls needed to fetch those entries and their fields. Over the allowed cost, you get MAX_RESOLVER_COST_EXCEEDED.



Both are worst-case estimates based on the limits in the query, not the data you have. A query for 100 blog posts, each with a reference connection of 75 related posts, counts as 100 + 100 × 75 = 7,600 documents, even if most posts have two related posts. It is rejected before it runs.

The fix is to lower the limits you pass, especially on nested connections:

```graphql
query BlogList($skip: Int = 0) {
  all_blog_post(limit: 20, skip: $skip) {
    total
    items {
      title
      url
      related_postsConnection(limit: 3) {
        edges {
          node {
            ... on BlogPost { title url }
          }
        }
      }
    }
  }
}
```

20 + 20 × 3 = 80 documents. If a detail page really needs every related item, fetch them in a separate query for that one entry and paginate the connection with skip and limit.

### MAX_ROOT_FETCH_LIMIT_EXCEEDED and the 25-item default

Root list queries like all_blog_post return 25 items when you pass no limit, and accept up to 100. Asking for more than 100 is rejected. Asking for nothing silently gives you 25. That second one is the bug that ships: a sitemap or generateStaticParams that builds 25 pages and nobody notices.

Paginate with skip and stop at total:

```typescript
type BlogListPage = { all_blog_post: { total: number; items: { url: string }[] } };

const PAGE_SIZE = 100;

export async function getAllBlogUrls() {
  const urls: string[] = [];
  let skip = 0;
  let total = Infinity;

  while (skip < total) {
    const data = await gql<BlogListPage>(
      `query ($skip: Int!) {
        all_blog_post(limit: ${PAGE_SIZE}, skip: $skip) { total items { url } }
      }`,
      { skip }
    );
    total = data.all_blog_post.total;
    urls.push(...data.all_blog_post.items.map((i) => i.url));
    skip += PAGE_SIZE;
  }

  return urls;
}
```

Keep the selection small in loops like this. A list of URLs is cheap. A list of URLs with three levels of references is where cost errors come from.

Reference connections have their own cap: up to 100 items per Reference field. Passing a higher limit returns MAX_REFERENCE_LIMIT_EXCEEDED.

### Too many content types in one request

A single request can query up to three content types at the root. A fourth returns MAX_QUERIED_CONTENT_TYPE_LIMIT_EXCEEDED. Split a "home page data" query that pulls page, navigation, footer and settings into two requests, and run them in parallel.

### The schema does not match my content model

The schema is generated from your content types when you query, so a model change shows up in the API right away. When it seems not to, the stale copy is usually on your side:

- Codegen output. Generated TypeScript types and persisted queries are a snapshot. Regenerate them after every content type change, ideally in CI.


- The wrong branch. Content type changes made on a branch only exist there. Pass the branch header with the branch UID or alias. Without it, the API reads main. A branch the delivery token is not scoped to returns INVALID_BRANCH.


- Typename collisions. Content type and field UIDs become GraphQL type names. Two UIDs that only differ by special characters collide and cause SCHEMA_BUILD_ERROR. UIDs that start with a number break queries entirely. Rename the UIDs. During introspection, you can pass skip_content_type_uids to leave the broken content types out while you fix them.



Branches and aliases are covered in [Safe content model changes with branches and aliases](/guides/safe-content-model-changes-with-branches-and-aliases).

### Type quirks

- Number fields map to Float in the default schema. Do not assume Int in generated types or in variables you compare against.


- Fields are nullable by default, even when they are mandatory in the content type. A required title can still be null if the entry failed to resolve. With strict type checks, mandatory fields become non-null (String!, [Edge!]!), and a missing value returns an error instead of null. Strict checks have to be enabled for your organization, and you request them with the x-graphql-strict-type-checks: true header.



## Check that it worked

Send the query with curl and look at the status, the body and errors together:

```bash
curl -s -o response.json -w "%{http_code}\n" \
  "https://graphql.contentstack.com/stacks/$CONTENTSTACK_API_KEY?environment=production" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ all_blog_post(limit: 20) { total items { title } } }"}'

jq '{errors: [.errors[]?.extensions.errors[]?.code], count: (.data.all_blog_post.items | length), total: .data.all_blog_post.total}' response.json
```

You want 200, an empty errors list, and a count that matches what you expect for the page. For pagination, the sum of all pages should equal total.

## Prevent it

- Route every GraphQL request through one wrapper that reads errors on 200 and logs the code and path.


- Set explicit limit values on every list and every reference connection. Never rely on the default 25.


- Budget queries by multiplying limits per level before you ship them. Stay well below 7,500.


- Keep reference chains at two levels in the model, so queries have room for one more when a design needs it.


- Regenerate GraphQL types in CI after content model changes, and pass the branch header explicitly in non-production environments.


- If you hit rate limits on top of these, [Fix 429 rate limit errors](/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish) covers backoff and caching.



## Key takeaways

- A non-2xx status means the query was rejected before it ran. The code is in extensions.errors[].code.


- HTTP 200 can still carry errors[], with the failing fields set to null. Check errors every time.


- References resolve up to three levels deep. Split the query or flatten the model rather than going deeper.


- Complexity counts every entry a query could fetch, up to 7,500. Lower nested connection limits to stay under it and under the resolver cost.


- Root lists default to 25 items and allow 100. Paginate with skip until you reach total.


- Schema mismatches are usually stale codegen, a missing branch header, or colliding UIDs.



## Next steps

- If you query REST instead, see [Nested references come back empty, or fail with error 141](/guides/nested-references-empty-or-error-141).


- See every delivery limit side by side in [Contentstack limits on one page](/guides/contentstack-limits-on-one-page).


- Start from a working GraphQL setup with the [Next.js GraphQL kickstart](/kickstarts/kickstart-next-graphql).





---

## Do this with AI

Install the cms-graphql skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills). Then ask your agent:

> Review this GraphQL query for my landing page, estimate its reference depth and how many entries it can fetch, and rewrite it so it stays under three reference levels and 7,500 documents, splitting it into two queries if needed.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### How deep can a Contentstack GraphQL query follow references?

Three levels. A deeper query is rejected with MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED before it runs.

### Why do I get HTTP 200 with an errors array?

The query ran, but some fields failed to resolve. Those fields are null in data and described in errors, so always check errors before you use data.

### Why does my list only return 25 entries?

25 is the default limit for root list queries. Pass limit up to 100 and paginate with skip, using total to know when to stop.

### What is resolver cost?

An estimate of the database calls a query needs. Queries above the allowed cost are rejected with MAX_RESOLVER_COST_EXCEEDED.

### Why are mandatory fields nullable in the generated types?

By default the schema marks fields as nullable. Strict type checks make them non-null, but they have to be enabled for your organization and requested with the x-graphql-strict-type-checks header.


---

## Step 6: Contentstack limits on one page

- **Source:** https://developers.contentstack.com/guides/contentstack-limits-on-one-page
- **Checkpoint:** You know the limits that apply to your plan and code.

- **Authors:** Tim Benniks
- **Published:** 2026-12-02T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:45.531Z
- **Level:** Beginner
- **Intent:** Learn
- **Tags:** api, headless, content_modeling

---

Contentstack limits are spread over dozens of documentation pages, and you usually find the right one after you hit the limit. This page collects the public limits in one place, grouped by area, so you can check a content model or a job before it fails.

Every value here comes from the public documentation and was checked in December 2026. Limits change, and many depend on your plan, so follow the docs link in each section for the current value.

## What you'll learn

- The API rate limits and why they are per organization


- How deep you can include references in REST and GraphQL


- The schema limits for content types, fields, Modular Blocks and Global fields


- The limits for taxonomy, entry variants, assets, publishing, webhooks, Launch and the CLI


- Which limits depend on your plan, and which guide helps when you hit one



## How to read this page

Plan-dependent means the documentation says the value depends on your plan, or that Contentstack support can raise it. Default values apply when nothing else is set for your organization. Where two documentation pages disagree, the table gives the value from the most recently updated page and says so.

Two things to keep in mind before the tables:

- Rate limits are per organization. Your builds, imports, scripts, Automate workflows and integrations all share them.


- Cached Delivery API responses are not rate limited. Only requests that reach the origin count. They all still count toward your overall API usage.



## API rate limits

Limit

Value

Plan-dependent

When you hit it

Docs

Content Delivery API, uncached requests

100 per second per organization

Yes

HTTP 429

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Image Delivery API, uncached requests

Counts toward the CDA limit

Yes

HTTP 429

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

GraphQL Content Delivery API, uncached requests

80 per second per organization

Yes

HTTP 429

[GraphQL](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api)

Content Management API, reads

10 per second per organization

Yes

HTTP 429

[CMA](https://www.contentstack.com/docs/developers/apis/content-management-api)

Content Management API, writes

10 per second per organization

Yes

HTTP 429

[CMA](https://www.contentstack.com/docs/developers/apis/content-management-api)

CMA bulk actions

1 request per second

Yes

HTTP 429

[CMA](https://www.contentstack.com/docs/developers/apis/content-management-api)

Stack creation

1 stack per minute per organization

No

Request rejected

[Stack limitations](https://www.contentstack.com/docs/headless-cms/stack-limitations)

The X-RateLimit-Limit and X-RateLimit-Remaining response headers show your actual limit and what's left in the current second. When you hit a rate limit, read [Fix 429 rate limit errors in builds, imports and bulk publish](/guides/fix-429-rate-limit-errors-in-builds-imports-and-bulk-publish). For timeouts and 5xx errors, read [ETIMEDOUT, 5xx and timeouts from the Delivery API](/guides/etimedout-5xx-and-timeouts-from-the-delivery-api).

## Content Delivery API (REST)

Limit

Value

Plan-dependent

When you hit it

Docs

Request URL size on the CDN

8 KB

No

HTTP 414 URI Too Long

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Entries or assets per response

100 by default; set more with limit and page with skip

No

You get the first page only

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Content types per "get all content types" response

100

No

Page with skip

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

include_all_depth

5 levels (include_all alone resolves 1)

No

Error

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Reference paths per request (include[] or include_all)

100

No

Error; reduce depth or includes

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Depth of a multiple content type Reference field

3 levels

No

Not documented

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Recursive embedded items (embedded_items_depth)

5 levels

No

Values above 5 are clamped to 5

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Sync API page size

100 items

No

You get a pagination_token for the next page

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Long $in lists and many includes push a URL past 8 KB. [Nested references empty or error 141](/guides/nested-references-empty-or-error-141) covers both.

## GraphQL Content Delivery API

Limit

Value

Plan-dependent

When you hit it

Docs

Nested reference depth

3 levels

No

Query rejected

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Reference depth in a where filter

3 levels

No

Query rejected

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Objects fetched in one query

7,500

No

Query rejected

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Referenced items per Reference field

100

No

Page with skip and limit on the connection

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Embedded items per JSON RTE field

100

No

Page the embedded items

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Content types queried in one request

3

No

Query rejected

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

Response size

7 MB

No

Query rejected

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

limit on a collection

25 by default, 100 maximum

No

Page with skip

[GraphQL](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api)

Content type schemas generated per request

100

No

Page the introspection schema

[GraphQL limitations](https://www.contentstack.com/docs/developers/apis/graphql-content-delivery-api/limitations)

GraphQL errors don't always come back as a non-200 status. [GraphQL errors decoded](/guides/graphql-errors-decoded) lists the error codes and what each one means.

## Content types, fields and Global fields

Limit

Value

Plan-dependent

When you hit it

Docs

Fields per content type, including nested fields

400

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Content type UID

200 characters; letters, numbers and underscores

No

Schema save rejected

[Content type limitations](https://www.contentstack.com/docs/developers/create-content-types/limitations-of-content-types)

Content type description

255 characters

No

Schema save rejected

[Content type limitations](https://www.contentstack.com/docs/developers/create-content-types/limitations-of-content-types)

Title field and Display Name

200 characters

Default

Save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Modular Blocks fields per content type

5

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Block definitions per Modular Blocks field

100

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Block instances per Modular Blocks field in an entry

100

Default

Entry save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Nested block levels

2

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Group nesting

5 levels

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Fields in a Group, including nested fields

100

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Global fields per content type

25

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Global fields per organization

1,000

Default

Creation rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Fields within a Global field

100

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Global field nesting

5 levels, including the parent

Default

Schema save rejected

[Global field limitations](https://www.contentstack.com/docs/developers/global-field/limitations-of-global-field)

Instances of a Global field marked Multiple

100

No

Entry save rejected

[Global field limitations](https://www.contentstack.com/docs/developers/global-field/limitations-of-global-field)

Custom fields per content type

10

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Select field options

100, each up to 100 characters

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Field visibility rules per content type

10 rules, 5 conditions and 5 target fields each

Default

Schema save rejected

[Field limitations](https://www.contentstack.com/docs/headless-cms/field-limitations)

Reference field query limit

100

No

Not documented

[Entries limitations](https://www.contentstack.com/docs/headless-cms/entries-limitations)

Tags per entry

50, each up to 50 characters

No

Entry save rejected

[Entries limitations](https://www.contentstack.com/docs/headless-cms/entries-limitations)

> Watch for: The Field Limitations page (updated November 2026) gives 400 fields per content type and 100 fields within a Global field. The older content type and Global field pages say 500 for both. Plan against the lower number.

Fields inside Modular Blocks, Groups and Global fields all count toward the content type total. [Modular Blocks, references or Global fields](/guides/modular-blocks-references-or-global-fields) helps you pick the structure that keeps the count down.

## Taxonomy

Limit

Value

Plan-dependent

When you hit it

Docs

Taxonomies per stack

Depends on your plan

Yes

Creation rejected

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

Terms per taxonomy

10,000

No

Term creation rejected

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

Terms per entry

25

No

Entry save rejected

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

Term depth

10 levels

No

Term creation rejected

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

Taxonomy and term name or UID

50 characters

No

Save rejected

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

Taxonomy fields per content type

1, which can hold several taxonomies

No

Not possible to add a second

[Taxonomy limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-taxonomy)

The Taxonomy field can't go inside Modular Blocks or Groups, and only published taxonomies are available through the Delivery API. [Querying content by taxonomy](/guides/querying-content-by-taxonomy) shows how the limits shape queries.

## Entry variants

Limit

Value

Plan-dependent

When you hit it

Docs

Variants merged with the base entry per CDN request

3

No

Only 3 variants are merged

[Entry variant limitations](https://www.contentstack.com/docs/headless-cms/limitations-for-entry-variants)

Timeout for entry variant requests

10 seconds

No

Request fails

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Response size, all variants of an entry

10 MB

No

Request fails

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Response size, a single entry variant

3 MB

No

Request fails

[CDA](https://www.contentstack.com/docs/developers/apis/content-delivery-api)

Entry variants need to be enabled for your organization, and custom queries only match base entry data. [Personalize variant returns base entry or null](/guides/personalize-variant-returns-base-entry-or-null) covers the most common problems.

## Stacks, branches, environments and locales

Limit

Value

Plan-dependent

When you hit it

Docs

Branches per stack

5

Yes

Creation rejected

[Stack limitations](https://www.contentstack.com/docs/headless-cms/stack-limitations)

Branch ID

15 characters, lowercase, _ as separator

No

Creation rejected

[Branch limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-branches)

Environments per stack

5

Default

Creation rejected

[Stack limitations](https://www.contentstack.com/docs/headless-cms/stack-limitations)

Fallback language levels

1

No

You can't chain fallbacks

[Localization limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-localization)

Management tokens per stack

10 valid at a time

No

Creation rejected

[CMA](https://www.contentstack.com/docs/developers/apis/content-management-api)

Authtokens per user

20 valid at a time

No

Not documented

[CMA](https://www.contentstack.com/docs/developers/apis/content-management-api)

The one-level fallback rule explains most "why am I getting en-us content" questions. [Locale fallback explained](/guides/why-am-i-getting-en-us-content-locale-fallback-explained) walks through it.

## Assets and images

Limit

Value

Plan-dependent

When you hit it

Docs

Asset file size

700 MB in the UI, 100 MB through the API

Can be raised

Upload rejected

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Assets per upload batch

10

Can be raised

Upload rejected

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Assets per stack

10,000

Can be raised

Upload rejected

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Image optimization input size

50 MB

Can be raised

Not documented

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Image optimization input dimensions

12,000 × 12,000 pixels

Can be raised

Not documented

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Image optimization output dimensions

8,192 × 8,192 pixels

Can be raised

Not documented

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

Animated GIF frames

1,000

Can be raised

Not documented

[Asset limitations](https://www.contentstack.com/docs/headless-cms/asset-limitations)

These apply to assets stored in a stack. The newer Assets product raises several of them. [Image transforms that surprise you](/guides/image-transforms-that-surprise-you) covers transform behavior.

## Publishing, bulk operations and releases

Limit

Value

Plan-dependent

When you hit it

Docs

Bulk publish or unpublish in the UI

100 entries, 10 languages, 10 environments at a time

Can be raised

Selection capped

[Bulk operation limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-bulk-operations-on-entries)

Items per bulk publish API request

10

Plan feature

Split into more requests

[CMA bulk operations](https://www.contentstack.com/docs/developers/apis/content-management-api/bulk-operations)

Select all records

10,000 entries

No

Only the first 10,000 are acted on

[Bulk operation limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-bulk-operations-on-entries)

Bulk delete in the UI

100 entries

Can be raised

Selection capped

[Bulk operation limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-bulk-operations-on-entries)

Scheduled bulk action

Up to 12 months ahead

No

Date rejected

[Bulk operation limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-bulk-operations-on-entries)

Nested reference publishing depth

5 levels

Yes

Deeper references aren't published

[Nested reference publishing](https://www.contentstack.com/docs/headless-cms/limitations-for-nested-reference-publishing)

Parent entries in a nested bulk publish

100

No

Selection capped

[Nested reference publishing](https://www.contentstack.com/docs/headless-cms/limitations-for-nested-reference-publishing)

Active bulk publish jobs per organization

2

No

Extra jobs wait

[Nested reference publishing](https://www.contentstack.com/docs/headless-cms/limitations-for-nested-reference-publishing)

Items in a release

500

No

Item not added

[Release limitations](https://www.contentstack.com/docs/headless-cms/releases-limitations)

Items added to a release per API request

25

No

Split into more requests

[Release limitations](https://www.contentstack.com/docs/headless-cms/releases-limitations)

Nested reference publishing doesn't apply when you publish through a release. [Releases, bulk publish and nested reference publishing explained](/blog/releases-bulk-publish-and-nested-reference-publishing-explained) compares the options, and [Publishing stuck or references not published](/guides/publishing-stuck-or-references-not-published) helps when a job doesn't finish.

## Webhooks

Limit

Value

Plan-dependent

When you hit it

Docs

Webhooks per stack

100

Can be raised

Creation rejected

[Webhook limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-webhooks)

Conditions per webhook

200

No

Save rejected

[Webhook limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-webhooks)

Emails notified when the circuit breaker disables a webhook

10

No

Save rejected

[Webhook limitations](https://www.contentstack.com/docs/headless-cms/limitations-of-webhooks)

[Webhooks: allowlisting, signatures and disabled endpoints](/guides/webhooks-allowlisting-signatures-and-disabled-endpoints) covers the circuit breaker and how to get a disabled webhook running again.

## Launch

Limit

Value

Plan-dependent

When you hit it

Docs

Request headers

About 10 KB

No

Request rejected

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Request body

128 KB on the platform limits page; the CF1001 error reference says 5 MB

No

Request rejected with 413 (CF1001)

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Response headers

32 KB

No

Response fails

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Response body

5 MB

No

Response fails

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Cloud Function and SSR request timeout

30 seconds by default, up to 780 seconds

Yes

Request times out

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Time to first response byte

98 seconds

No

Connection closes

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Cache revalidations per day

500 (Enterprise: 2,000)

Yes

Revalidation rejected until 00:00 UTC

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

Origin delivery rate

200 requests per second (Enterprise: 1,200)

Yes

Origin requests throttled

[Launch platform limits](https://www.contentstack.com/docs/launch/platform-limits-on-launch)

The origin delivery limit counts cache misses to your site's origin, separate from the API rate limits your code calls. Edge function limits, environment variable limits and log retention are in [Logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits). The error codes you see when a Launch limit is hit are in [Launch error codes decoded](/guides/launch-error-codes-decoded).

## CLI

Limit

Value

Plan-dependent

When you hit it

Docs

Request and response size (maxContentLength, maxBodyLength)

100 MB by default

Configurable in the config file

Export or import fails

[CLI import](https://www.contentstack.com/docs/headless-cms/import-content-using-the-cli)

Share of the rate limit the CLI uses

50% by default

Configurable with csdx config:set:rate-limit

Slower jobs, fewer 429s

[CLI rate limits](https://www.contentstack.com/docs/headless-cms/configure-rate-limits-in-the-cli)

[csdx import and export failures](/guides/csdx-import-and-export-failures) covers memory errors and other ways large CLI jobs fail.

## Key takeaways

- API rate limits are per organization: 100 uncached CDA requests per second, 80 for GraphQL, 10 reads and 10 writes for the CMA, 1 per second for bulk actions. Your plan can change all of them.


- Cached Delivery API responses don't count against the rate limit, so caching is the cheapest way to stay under it.


- REST includes go 5 levels deep with at most 100 reference paths. GraphQL goes 3 levels deep and returns at most 7 MB.


- A content type holds 400 fields in total, counting everything inside Modular Blocks, Groups and Global fields.


- Taxonomies allow 25 terms per entry and 10 levels of depth. Releases hold 500 items.


- On Launch, server functions time out after 30 seconds by default, and responses are capped at 5 MB.


- Values were checked in December 2026. Follow the docs link in each section for the current number.





---

## Do this with AI

Install the cms-data-modeling-best-practices skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Modeler profile in MCP Profile Hub. Then ask your agent:

> Go through every content type in my stack and report which ones are close to a limit: more than 300 fields in total, more than 20 Global fields, Modular Blocks nested 2 levels deep, or more than 80 block definitions in one Modular Blocks field. Suggest how to simplify the worst three, but don't change any schema.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Are Contentstack rate limits per stack or per organization?

Per organization. Every stack, build, script and integration in the organization shares the same API rate limits.

### Can Contentstack limits be raised?

Many can. Rate limits, nested reference publishing depth, the number of taxonomies and branches, and several asset and webhook limits depend on your plan or can be raised by Contentstack support.

### How many fields can a content type have?

The Field Limitations page lists a maximum of 400 fields per content type, counting fields inside Modular Blocks, groups and Global fields.

### How deep can I include references in one Delivery API request?

Up to 5 levels with include_all_depth on the REST Delivery API, and up to 100 reference paths per request. GraphQL fetches nested references up to 3 levels deep.

### When were these values checked?

In December 2026, against the public Contentstack documentation. Each section links to the page it comes from, so check there for the current value.

