Rate Limiting

Important This section only applies to Cloud CMS Hosted Subscriptions

Your Cloud CMS subscription may be configured to limit the number of concurrent API calls you are allowed
to make per band. This is known as rate-limiting. When the number of concurrent API calls exceeds your tenant's
configured rate limit for a given band, you will experience rate limiting.

Generally, this consists of receiving an HTTP 429 response code and response headers that describe the
rate limiting. The application making the API call is then responsible for interpreting this information
to re-attempt the call in the future.

Each subscription supports one or more bands. By default, every subscription has one band (known as the
default band) that handles 100% of the subscription bandwidth.

If not otherwise specified, API requests use the default band.

How it Works

When Cloud CMS receives a request, it estimates the number of points required to service the request. A simple
call with low processing requirements will generally cost 1 point. A more expensive call with longer anticipated
execution time may cost more points.

For example, the following types of operations may require more points due to longer execution times:

  • A long-running query that pulls back a very large result set and relies on unindexed collections.
  • A deeply-nested GraphQL query that traverses down many layers with custom queries.
  • A composite find call that performs a merge between Elastic Search and MongoDB paginated search results.

Depending on how long the anticipated execution time is, these calls may be assigned a larger number of points.

The system then looks to the requester's subscription and band configuration to determine the maximum number of points
that may be used to service concurrent requests for the specified band. If a band is not specified, the default
band is used (this band receives 100% of the subscription bandwidth).

If the maximum number of points is exceeded for the band, an HTTP 429 (Too Many Requests) status code
is returned.

Headers

For any HTTP request made to the API, the following response headers will be handed back:

  • X-RateLimit-Limit - the maximum number of rate limit points allowed by your subscription
  • X-RateLimit-Remaining - the number of unused rate limit points remaining
  • X-RateLimit-Consumed - the number of rate limit points currently in use

If an HTTP request is rate-limited, the response status code will be 429 (Too Many Requests).

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429

If you receive a 429 status code, you will also receive the following supplementary headers:

  • Retry-After - the number of seconds to wait before you should reattempt the request
  • X-RateLimit-Reset - the earliest date when you should reattempt the request

These two headers effectively provide the same information -- they indicate a future time when
sufficient points are expected to be available to service your request.

Bands

As noted, each subscription supports one or more bands.

Every API request is allowed to specify the band it should be executed against. You can do this via one
of the following ways:

  • using the band request parameter
  • using the x-cloudcms-band-id header
  • using the cloudcms-band-id cookie

If a band is not specified via any of these methods, the default band is assumed.

Here is an example of an API URL with the custom band specified:

POST /repositories/65c3d4723cd020e5a2f5/branches/3b54b21c2e76ae7fbdfd/nodes/query?band=custom1

By default, each subscription has a single default band that supports 100% of the subscription's bandwidth.

If a subscription supports 100 points for the rate limiter and has a single default band, then that band
will support 100 points all by itself.

Benefits

By splitting your subscription bandwidth up into multiple bands, you make it possible for your critical or live
applications to have dedicated bandwidth. This prevents other applications within your business (such as
other applications, content loaders, test runners, continuous integration tools and so forth) from running up
the rate limit and potentially causing your live applications to break.

Suppose, for example, that you had a live application and several non-critical applications. In this case, you
could create a live band to work alongside your default band. The live band might support 100 points and
the default band might likewise support 100 points.

You would then set up your live application so that its API calls apply one of the following with every request:

  • either set the band request parameter to live
  • or set the x-cloudcms-band-id header to live
  • or set the cloudcms-band-id cookie to live

Only one of these is needed. The API will pick up the band information and your rate limit accurals will be
calculated against that band. In this case, the live band will be decremented.

Other less-critical applications would continue to use the default band. If they flooded connections on that
default band, it would have no impact on the live band as it has its own dedicated bandwidth. The only
application that could impact the live band would be the live application itself.