The API uses per-second rate limits. Limits are applied per API key.
Default limits
| Operation | Limit |
|---|---|
| Read requests (GET) | 20 requests/second |
| Write requests (POST, PUT, PATCH, DELETE) | 5 requests/second |
Rate limit headers
Every response includes rate limit information:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per second |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Exceeding the limit
When you exceed the rate limit, the API returns 429 Too Many Requests:
{
"error": {
"type": "rate_limit_error",
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded the rate limit of 20 requests per second.",
"retryable": true,
"request_id": "req_a1b2c3d4e5f6",
"retry_after_seconds": 1
}
}
The response also includes a Retry-After header with the number of seconds to wait.
Best practices
- Respect
Retry-After— wait the indicated time before retrying - Use exponential backoff — if retries keep failing, increase the wait time
- Cache responses — store results locally to avoid redundant requests
- Use
last_activity_since— for sync workflows, only fetch conversations with new activity instead of re-fetching everything - Use
total_count— to answer "how many?" questions without paginating through all results