Updated on September 21, 2021

To ensure resiliency against DOS and enforce a fair-use policy, the Crisp API has a multi-level rate-limit (based on client IP and user identifier, if authenticated).

Types of Rate Limits

Limiter Description Classifiers Tiers
Load Balancers Very permissive rate limit on Crisp edge load balancers; you should not hit against this limit very often IP Address user plugin
API Global Permissive, API-wide rate limit that limits the total amount of requests a given IP and user identifier can submit to the API IP Address User ID user
API Route More restrictive, per-route rate limit based on user identifier if authenticated, or client IP IP Address User ID user
Plugin Quota Only applies to permanent tokens, daily request quota that is allowed to the plugin) Plugin ID plugin

What Happens Upon Being Rate-Limited?

If your client gets rate-limited, you will start receiving 429 Too Many Requests or 420 Enhance Your Calm HTTP errors in response to your requests.

The limiter that raised this error could be global or per-route, based on how you triggered our rate-limiting systems.

Where Limits Do Not Apply?

1. Plugin tokens

Note that plugin tokens are not subject to the following rate-limits: API Global and API Route. This allows plugins to send bursts of requests, which is typical for integrations.

Though, those tokens are subject to a special rate limiter, named Plugin Quota.

This rate-limiter is built on a quota system, reset daily, that lets a plugin perform a certain number of requests to the API until it gets limited.

If your integration gets quota limit errors, then you should request a daily quota increase on the Marketplace.

2. Cached routes

Be aware that GET and HEAD routes, although rate-limited, use a cache layer which allows you to hit a route more often that you usually should without triggering the API rate limiting system (once a cached response is served).

You can see the cache status of a response via the Bloom-Status HTTP header (possible values: MISS, HIT, DIRECT, OFFLINE).

If you are curious, the cache layer is powered by Bloom, an open-source Crisp project.