Rate limits

Limits

• 1,000 requests per minute per workspace, summed across every API key.
• 120 requests per minute per API key burst — enforced as a 10-second sliding window of 20 requests.
• 5,000 outbound emails per workspace per hour — independent of the request budget. Sends rejected at this layer return 429 with code: "send_quota_exhausted".

Response headers

Every response carries the current state of the budget so you can pace yourself without trial-and-error. Headers follow the IETF RateLimit Header Fields draft.

• RateLimit-Limit — the active per-key budget (120).
• RateLimit-Remaining — requests left in the current window.
• RateLimit-Reset — seconds until the window opens fully again.
• Retry-After — present on 429 responses; integer seconds.

429 Too Many Requests

When you hit the limit Cold OS returns 429 with the canonical error envelope. Honour Retry-After exactly — the value is the number of seconds until the next request is guaranteed to be accepted.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API key burst limit exceeded. Retry in 7s.",
    "request_id": "req_01HZSBB2C3D4E5F6G7H8J9K0L1"
  }
}

Best practices

• Use cursor pagination. The cursor param on every list endpoint is opaque and forward-only — pass back the previous response’s next_cursor. Don’t parse it; the format will change.
• Filter with updated_since. Polling for changes? Pass the timestamp of your last successful sync.
• Batch where possible. POST /v1/pools/{id}/members takes 500 contact ids per call.
• Respect Retry-After. Exponential backoff is fine; ignoring the header is not.