Usage Plans & Rate Limits

This page describes the rate limits and quotas for our API across different usage plans. These limits apply to the Core, Conversation Hub, and Knowledge Hub APIs. API version availability varies by service — some services support both v3 and v4, while newer services are available in v4 only. The rate limit tables below indicate the version(s) applicable to each service.

Crucially, rate limits are applied on a per-endpoint basis.

• Independent Buckets: Each individual endpoint path (e.g., GET /folders, POST /folders, GET /articles) has its own dedicated rate limit bucket.
• Isolation: If one endpoint hits its limit and returns a 429 Too Many Requests error, other endpoints in that collection are not affected. You can continue calling other APIs without interruption.

• Rate Limit: The maximum number of API calls allowed per second for a specific endpoint.
• Per-Endpoint Isolation: Each endpoint's traffic is tracked independently. Throttling on one resource does not trigger throttling on others.
• Scope: Rate limits are applied per tenant. All requests made under the same tenant share the same limit buckets for each endpoint, regardless of which application or integration is making the call.

For each API collection listed below:

1. Standard Limits: Every endpoint in that collection (unless listed as "Special") has the rate defined in the Rate Limit column. For example, if the limit is 0.5 req/sec, Endpoint A and Endpoint B each get 0.5 independently.
2. Special Endpoints: This column lists specific paths that have their own unique limits. These "Special" limits override the standard limits for that specific path only.

Our system utilizes a Token Bucket algorithm to manage traffic. Every unique endpoint path has its own independent bucket.

1. Individual Buckets: Your plan provides a separate "bucket" for every endpoint.
2. Refill Rate: Each bucket refills at the "Rate Limit" frequency (e.g., if the limit is 0.5 req/sec, the bucket refills at a rate of 1 token every 2 seconds).
3. Independent Consumption: Calling Endpoint A only consumes tokens from Bucket A. Bucket B remains full and ready for use.

Plan: Basic Plan — Case Manager (Rate Limit: 0.5 req/sec)

• Scenario: You send a high volume of requests to GET /cases and receive a 429 Too Many Requests error.
• Result: While GET /cases is throttled, you can still immediately call GET /cases/{id} or POST /cases. Because those are different endpoint paths, their rate limit buckets are completely independent and will still be available.

When an individual endpoint exceeds its rate limit, the API returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "code": "429-001",
  "developerMessage": "Too many requests."
}

1. Per-Endpoint Backoff: If you receive a 429, only pause or "back off" requests to that specific endpoint. You do not need to stop traffic to other endpoints in the same API.
2. Implement Exponential Backoff: We recommend an exponential backoff strategy (e.g., wait 1s, then 2s, then 4s) for the specific resource being throttled.
3. Client-Side Throttling: We recommend implementing your own client-side rate limiting to match the values in the tables above.
4. Cache When Possible: Reduce the frequency of calls to static resources (like Folder or Department lists) by caching responses to avoid hitting per-endpoint limits.