API rate limiting

IBM® NS1 Connect® uses API rate limits to control the number of API requests per account issued over a period of time.

Doing so allows distribution of resources equitably and ensures high performance for all platform users. API limiting implementation is flexible and based on the token bucket algorithm, which allows a certain number of requests within a period of time. Available tokens may be used as quickly as your automation can send requests. The platform employs automatic abuse thresholds to protect the platform.

Tokens are only replenished at a rate equal to the number of requests allowed per period divided by the number of seconds in a period. When a user makes an API request to NS1 Connect, the response includes additional headers that provide precise API rate-limiting information, including:

Note: Automatic abuse thresholds are in place to protect the platform, and hard rate-limiting by these mechanisms is possible if the platform observes excessive requests at a rate considered abusive.

The number of tokens per rate-limit period for the endpoint
The number of seconds in the rate-limit period
The number of tokens remaining in the current period

The number of tokens (allowed requests) per period may vary by API endpoint. For example, a simple GET request might grant a user a maximum of 900 tokens (allowed requests) with a rate-limit period of 300 seconds. The user can use the 900-token limit as quickly as necessary. Each request will decrease the remaining amount by a single token. The replenishment rate for this route would be 900 / 300 = 3 tokens per second. This allows the user to pace their application to steadily make requests while avoiding the limit or to submit multiple requests in bursts and wait for the tokens to replenish.

Other routes, such as POST or PUT, are more computationally expensive and, therefore, have lower rate limits. POST requests, for example, might have a rate limit closer to 300 requests per 300 seconds; therefore, tokens would only be restored to the account at a rate of one request per second. It is best to strategically develop your applications to work with this implementation and avoid interruptions while making changes.

Current rate limit data for all requests can be found in each API response by including the -v flag in your cURL command. For example, the following request includes the -v flag to include the rate limit for this endpoint in the response:

curl -v -X GET -H "X-NSONE-Key: ${NSONE_API_KEY}' https://api.nsone.net/v1/monitoring/regions

Example response:

> GET /v1/monitoring/regions HTTP/1.1
< HTTP/1.1 200 OK
...
< x-ratelimit-by: customer
< x-ratelimit-limit: 100
< x-ratelimit-period: 1
< x-ratelimit-remaining: 99

curl -v -X GET -H "X-NSONE-Key: ${NSONE_API_KEY}' https://api.nsone.net/v1/monitoring/regions