Rate limits

​

Default limits

​

Rate limit headers

​

Exceeding the limit

{
  "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
  }
}

​

Best practices

1. Respect Retry-After — wait the indicated time before retrying
2. Use exponential backoff — if retries keep failing, increase the wait time
3. Cache responses — store results locally to avoid redundant requests
4. Use last_activity_since — for sync workflows, only fetch conversations with new activity instead of re-fetching everything
5. Use total_count — to answer “how many?” questions without paginating through all results