Rate Limits

Cloud9 enforces rate limits across all its API endpoints to provide a seamless experience for our customers by fairly allocating access to our APIs across all firms.

Rate limits are defined by a maximum number of requests within a rolling 60 second window per API endpoint per region for each firm.

Requests to the Cloud9 APIs are subject to the following limits:

API	Requests per minute
Call Data API	20
Management API	20
Monitoring API	20

Some endpoints have their own rate limits:

Call Data API:

Method	Endpoint Path	Requests per minute
POST	v1/calls/metadata	70
PATCH	v1/calls/metadata	20
POST	v1/calls/recordings	350
POST	v1/calls/recordingRecords	20
POST	v1.1/calls/metadata	70

Management API:

Method	Endpoint Path	Requests per minute
POST	external/apis/connections	40
PUT	external/apis/connections	5
GET	external/apis/connectionApprovals	20
PUT	external/apis/connectionApprovals	5
POST	external/apis/roles	5
POST	external/apis/users	40
POST	external/apis/groups	20
POST	external/apis/logout	5
POST	v1.1/external/apis/users	40
POST	external/apis/users/{userId}/traderLayout	20

Monitoring API:

Method	Endpoint Path	Requests per minute
POST	external/apis/audit	6
POST	external/apis/alert	6
POST	external/apis/userPresence	6

When the limit is reached, any new incoming calls are BLOCKED from processing until the time limit window has been reached. For example, a firm, regardless of the number of API keys used, is allowed a maximum of 20 requests per minute per region on the endpoint POST: v1/calls/metadata. If the limit is exceeded, then the firm must wait until the number of requests begins to replenish, which will be 60 seconds after the first of the 20 requests

Rate limit indicators:

Each HTTP call will return a set of headers that indicate limit consumption:

Header	Description
X-C9-RateLimit-Limit	Shows the value of the limit
X-C9-RateLimit-Refresh-Interval-Millis: 60000	Shows the limit refresh rate period in milliseconds
X-C9-RateLimit-Reset-Millis: 26394	Shows the number of milliseconds remaining when the limit will replenish
X-C9-RateLimit-Enforcement: BLOCK,LOG	Shows the limit enforcement strategies used. Block will prevent more requests whereas Log means we have logged the attempt
X-C9-RateLimit-Key-Used: rateLimit:13:Calls_Data	Shows the resource in scope for limit enforcement
X-C9-RateLimit-Remaining: 3	Shows the current usage of the limit for the specified in X-C9-RateLimit-Key-Used

When the rate limit is reached, the API response “429 Too Many Requests” is returned anytime a user makes an API call and the rate limit for the API endpoint has already been reached.

Code Examples:

The description and examples in this document demonstrate how to use rate limit headers when API request fails with Too Many Requests(429) error code.

import axios from "axios";

let rateLimitHeaders = {
    const limit = "x-c9-ratelimit-limit";
    const rateLimitRemaining = "x-c9-ratelimit-remaining";
    const refreshIntervalMillis = "x-c9-ratelimit-refresh-interval-millis";
    const resetMillis = "x-c9-ratelimit-reset-millis";
    const keyUsed = "x-c9-ratelimit-key-used";
    const enforcement = "x-c9-ratelimit-enforcement";
}

let requestBody = {
    "beginDate": "2022-04-30 01:00:00",
    "endDate": "2022-04-30 23:59:59",
    "pageSize": 20
};

const noOfRequests = 35; //change this to desired value to hit ratelimits

function logRateLimits(is429, headers) {
    let limit = headers[rateLimitHeaders.limit];
    let remainingLimit = headers[rateLimitHeaders.rateLimitRemaining];
    let limitResetInMillis = headers[rateLimitHeaders.resetMillis];
    let limitRefreshInMillis = headers[rateLimitHeaders.refreshIntervalMillis];
    if (is429) {
        console.log(`Rate limit breached. Limit is ${limit} requests per ${limitRefreshInMillis} milliseconds for this endpoint, wait ${limitResetInMillis} milliseconds and retry.`);
    } else {
        console.log(`Remaining ${remainingLimit} requests out of ${limit} requests for the next ${limitResetInMillis} milliseconds.`)
    }
}

let totalRequests = 0;

function postRequest(requestBody) {

    if (totalRequests > noOfRequests) return;
    ++totalRequests;

    // encode to HMAC SHA 512
    let digest = createDigest(requestBody);

    const url = config.protocol + '://' + config.requestURI + config.path;
    return axios.post(url, requestBody, {
        headers: {
            'Authorization': digest,
            'Content-Type': config.contentType,
            'Date': new Date().toUTCString()
        },
        decompress: false //this is necessary as axios failed to decode the response when a request fails
    }).then(response => {

        console.log("response code: " + response.status);
        logRateLimits(response.status === 429, response.headers);
        //issue another request to hit rate limit
        postRequest(requestBody);

    }).catch(error => {
        if (!error.response) {
            console.log("response is empty in error handler");
            console.log(error);
            return;
        }
        if (error.response.status === 429) {

            const headers = error.response.headers;
            logRateLimits(error.response.status === 429, headers); // log rate limits
            const resetMillis = headers[rateLimitHeaders.resetMillis]; //read rate limit header

            if (resetMillis > 0) {

                //sleep for milliseconds 'resetMillis' to try again!
                setTimeout(() => {
                //retry with another request after rate limits reset
                postRequest(requestBody);
                }, resetMillis);

            }
        } else {
            console.log(error);
        }
    });
}

 postRequest(requestBody);