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.
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).