Deprecation warning - version 1 of the Capsule API will not be available after January 31, 2018. Developers should use version 2 when developing their applications. Developers who have already built applications please check our migration guide on how to move your applications to the latest version.

Rate Limiting

For requests using Basic Authentication, each Capsule user can make up to 4,000 requests per hour.

All successful API requests include the following three headers with details about the current rate limit status:

  • X-RateLimit-Limit - The maximum number of requests that the user is allowed to make per hour.
  • X-RateLimit-Remaining - The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset - The time at which the current rate limit window resets in UTC epoch seconds.
HTTP/1.1 200 OK
X-RateLimit-Limit: 4000
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1434037662
...

Once you go over the rate limit all API requests will receive an error response until the rate limit quota is reset:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 4000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1434037662
{
  "error": "rate limit reached"
}

After receiving such a responses your application should wait until the time inside the X-RateLimit-Reset header before it makes any other API requests for the specific user.

If you repeatedly continue to make API requests after reaching the rate limit and this causes excessive load, we may temporarily block the application or disable the user account to prevent the excessive load affecting other users of the system.

Avoiding the Rate Limit

If you are exceeding the rate limit, you can likely fix the issue by throttling requests (e.g adding a delay between requests) or by caching API responses. The lastmodified query parameter and the /api/<type>/deleted endpoints allows to keep your local version up to date with the Capsule version.

Including ?lastmodified=<date> query parameter in list parties, list opportunities and list cases requests will retrieve only entities added or updated after the specified date (UTC timezone). The date must be provided in the following format YYYYMMDDTHHMMSS. eg. Midnight June 31, 2015 GMT would be 20150631T000000.

You can also retrieve parties that where deleted after a specific date by making a GET request for api/party/deleted?since=<date>. This will return a list of parties ids that where deleted inside Capsule so you can remove them from your local database or cache. Similar endpoints are available for opportunities and cases.

If you’re already using these features and still exceeding your rate limit, please contact us.