Unless specified otherwise, all requests to the API are rate limited to prevent abuse, accidental or otherwise. It is not intended for this rate limit to interfere with any legitimate use of the API. The limits vary depending on the type of client that is accessing the API, according to the following rules (unless specified otherwise by the specific API endpoint):
| Client Type | Description | Limit |
|---|---|---|
| Non-Authenticated/Anonymous User | Users that are not logged in, i.e. anonymous; requests are associated by IP address. | 1800 requests per hour. Equivalent to 0.5 requests per second. |
| Authenticated User w/ Non-Premium Plan | Users that are authenticated but do not belong to an org that has a premium (paid) subscription. | 5400 requests per hour. Equivalent to 1.5 requests per second. |
| Authenticated User w/ Premium Plan | Users that are authenticated and belong to an org that has a premium (paid) subscription. | 10800 requests per hour. Equivalent to 3.0 requests per second. |
Additionally, the default download domain has a limit of 10,000 requests per 5 minutes (600 seconds). Custom domains can have higher limits.
Need Higher Limits?
No problem! If you're on a non-premium plan, then all you need to do is activate a premium plan. If you're already on a premium plan then we'll be happy to raise the limit for you, just send us a description of the use case and the desired limit to us, and we'll take care of it.
Every response from the API will include the following headers to provide information about the current rate limit status:
| Header | Meaning | Example |
|---|---|---|
| X-RateLimit-Limit | The maximum number of requests that the client is permitted to send per hour. | 600 |
| X-RateLimit-Remaining | The number of requests that are remaining in the current rate limit window. | 588 |
| X-RateLimit-Reset | The UTC epoch timestamp at which the current rate limit window will reset. | 1485706850 |
| X-RateLimit-Interval | The time in seconds that client is suggested to wait until the next request in order to avoid consuming too much within the rate limit window. | 0.98256663893 |
| Retry-After | The time in seconds to wait before the next request will be allowed (only sent if the request has been throttled). | 3384 |
Let's see it in action:
curl -i http://api.cloudsmith.io/user/self/
HTTP/1.0 200 OK
X-RateLimit-Interval: 60.0
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1485712175
Date: Sun, 29 Jan 2017 16:49:34 GMT
If the client has exceeded the rate limit in a particular rate limit window a 429 Too Many Requests status code will be sent instead of acting upon the request. The body response will be JSON encoded and include a detail message. Let's see it in action:
curl -i http://api.cloudsmith.io/user/self/
HTTP/1.0 429 Too Many Requests
Allow: GET, OPTIONS
Content-Type: application/json
Retry-After: 3304
Vary: Cookie
x-content-type-options: nosniff
X-Frame-Options: SAMEORIGIN
X-RateLimit-Interval: 3303.55762601
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1485712175
Date: Sun, 29 Jan 2017 16:54:30 GMT
{
"detail": "Request was throttled. Expected available in 3304.0 seconds."
}