Content Delivery API

CDA Technical Limits & Rate Limits

These are limits for the GraphQL Content Delivery API

For limits applicable to the REST Content Management API, please instead see CMA Technical Limits & Rate Limits

Our shared-service infrastructure is built to maintain steady performance for every customer, thanks to carefully set technical limits. If any API call or CMS action goes over these boundaries, it'll trigger an error message. Should your project require higher limits, get in touch with us to discuss further.

CDA Technical Limits

Here are the technical limits currently in place for the CDA:

GraphQL complexity cost: 10,000,000 (read more)
Real-time Updates API: max. 500 concurrent connections per project (read more)

CDA Rate Limits

The Content Delivery API is is meant for delivering content from DatoCMS to apps, websites and other digital products consumed by end-users. To improve performance, we cache CDA calls whenever possible, but uncached calls that hit our origin servers will have rate limits applied.

Cached CDA calls have no rate limit (but are still billed per API request).

Uncached CDA calls have two simultaneously active rate limits:

40 requests/second
1000 requests/min

Both limits are always in effect, and uncached requests must stay within both.

HTTP Headers for CDA Rate Limits

Each CDA response will include these HTTP headers to help you stay within the rate limits:

cf-cache-status: Either HIT or MISS. Requests that HIT the cache bypass rate limits. Rate limits only apply to requests that MISS the cache and hit our origin.
x-cacheable-on-cdn: Whether the request can ever be cached (either true or false). If false, the request is too big or complex to cache, and will always be subject to rate limits.
x-ratelimit-limit: Either 40 or 1000, depending on which rate limit (per-second or per-minute) you're currently closest to hitting.
x-ratelimit-remaining: How many requests you have remaining, depending on the limit you're closest to hitting (per-second or per-minute).
x-cacheable-on-cdn-query-length-limit: Request body size in bytes (e.g. 273/8192)
x-complexity: Estimated GraphQL query complexity.
x-request-id: An internal UUID that helps us troubleshoot specific API requests. Please include this in support requests.

Exceeding either CDA rate limit will cause the HTTP status code to become 429 Too Many Requests, and an additional header will be added:

x-ratelimit-reset: Number of seconds until next refill. Can be either 1 for the per-second limit or an integer < 60 for the per-minute limit.

429 Status Responses in Shared Infrastructure

Even if you're operating within your rate limits, there's still a chance of encountering a 429 status code while using the DatoCMS shared infrastructure or medium-density infrastructure during peak system load.

Although this is uncommon, it's wise to be proactive in dealing with this situation. To handle it effectively, it's recommended to implement a retry mechanism. If you receive a 429 status response, wait for a few seconds before attempting the request again.

CDA Rate Limit Examples

You make 60 requests at once and hit the per-second limit immediately. The last 20 requests will be rejected with a 429. You should retry again after x-ratelimit-reset: 1 second.
You sustain 40 requests/second and stay within the per-second limit. But after 25 seconds, you will hit the per-minute limit. Remaining requests are rejected with a 429. You should retry again after x-ratelimit-reset: 35 seconds.

You sustain 16 requests/second and stay under both limits indefinitely. Well done!

How CDA Query Caching Works

Whenever you make a CDA (GraphQL) query, our CDN will evaluate its request and response and attempt to cache it for subsequent queries coming from the same region/point of presence. You can check the HTTP response headers (see above) to see if the query was successfully cached.

The query cache gets invalidated selectively based on the objects referenced in the query and the payload. As a rule of thumb, when you update a specific model/record/asset, all GraphQL queries that reference those object will automatically get invalidated. Each PoP will then make new requests to the Content Delivery API, and cache the new result for future requests.

CDN Caching limitations for extremely large requests

If the body of your GraphQL request, after being compressed using gzip, exceeds 8KB in size, it will not be cached by our CDN. Consequently, these queries will be directed to the Content Delivery API origin servers, resulting in slower performance and being subjected to the rate limits mentioned above.

The efficiency of the gzip compression algorithm makes it highly unlikely that requests will exceed the 8KB limit. To give a rough estimate, 99% of our customers will never experience this limitation. However, it is important to be aware of this limitation and check the GraphQL queries if you notice a suspicious number of 429 status codes.

Reaching your plan monthly API calls limit

For projects under a paid plan, even exceeding the API calls or bandwidth limit does not lead to the interruption of the service, but the payment of an additional fee commensurate with the use. For projects under a free plan, service will be temporarily disabled until the beginning of the following calendar month, unless you provide a credit card.

For more details, check our Plans, billing and pricing page.