Content Delivery API

Technical Limits (CDA)

These are limits for the GraphQL Content Delivery API

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

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.

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 Rate limits specify the number of requests a client in a specific time frame.

Since this API is meant to be used for delivering content from DatoCMS to apps, websites and other digital products consumed by end-users, there are no rate-limits enforced on requests that hit our CDN cache. The calls will still count against the monthly quota, even if cached.

For requests that do hit the Content Delivery API we enforce a rate limit of 40 requests per second and 1,000 requests per minute per API token. When these limits are exceeded, the API will respond with a status code of 429.

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.

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 get invalidated. Each PoP will then make new requests to the Content Delivery API, and cache the new result for future requests.

HTTP Response Headers for CDA Limits

Each CDA response contains several HTTP headers that helps you stay within the limits:

x-cacheable-on-cdn: Indicates whether the request can be cached by our CDN (either true or false)
x-cacheable-on-cdn-query-length-limit: The actual size of the compressed body request in bytes (e.g. 273/8192)
x-complexity: The estimated GraphQL query complexity.
x-request-id: A DatoCMS internal-use UUID that helps us troubleshoot specific API requests. If you're encountering problems with the CDA, whether related to limits or otherwise, logging this UUID will help our support team better diagnose the problem.
cf-cache-status: Either HIT or MISS. Cached requests are NOT subject to rate limits, but are still billed per-request (i.e., a response of HIT is not rate-limited, but still costs you 1 CDA request credit).
Following an invalidation, the first CDA request to hit a particular CDN edge node will always be MISS, since the CDN has to fetch refetch the query from our origin. Subsequent repeats of the same requests to the same edge node should be HIT if x-cacheable-on-cdn is true. Visitors from different regions of the world may hit different CDN edge nodes, so a query cached in one part of the world may still cause a cache miss in other parts of the world.

For uncached requests hitting our origin (these will only be present if cf-cache-status is MISS), rate limits apply:

x-ratelimit-limit: Will return either 40 or 1000, depending on which rate limit you're currently close to (40 per second or 1000 per minute). Both rate limits are always in effect, but this header tells you which one you're more at risk of.
x-ratelimit-remaining: How many requests you have remaining in the current bucket. For example, if the response's x-ratelimit-limit says 40 and x-ratelimit-remaining says 39, you have 39 requests left this second. If x-ratelimit-limit says 1000 and x-ratelimit-remaining is 999, you have 999 left for this minute.
x-ratelimit-reset: This header only appears if you already hit a rate limit, and indicates how long you should wait to retry again. It returns an integer in seconds, like 1 (for the per-second rate limit) or 59 (for the per-minute rate limit).

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.