Rate Limits & Best Practices

How requests are throttled and how to design a reliable integration.

Rate limits

The API enforces a sliding window of 60 requests per 60 seconds per organization, regardless of credential type. Multiple API keys or OAuth tokens belonging to the same org share the same bucket.

Every response includes rate‑limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1747500000

When you exceed the limit you'll receive 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Limit is 60 requests per 60 seconds.",
  "retry_after": 12
}

Both the JSON body and the Retry-After header tell you how many seconds to wait. Back off at least that long before retrying.

Best practices

Use webhooks instead of polling

For change notifications, subscribe to webhook events. Polling GET /api-contacts?updated_since=... works, but webhooks are lower‑latency and consume far fewer of your 60 requests per minute.

Batch where possible

Prefer one paginated list call over many GET /:id calls.

Use updated_since for delta syncs

GET /api-contacts?updated_since=2026-05-17T00:00:00Z

Similar parameters exist on related endpoints:

• /api-deals → created_since, updated_since
• /api-activities → created_since
• /api-contacts/:id/deals → created_since
• /api-contacts/:id/activities → created_since

Handle 5xx and 429 with exponential backoff

A reasonable schedule: 1s, 2s, 4s, 8s, 16s, then log and give up. Always honor Retry-After first when present.

Pagination

List endpoints accept limit and offset. Defaults and caps vary by endpoint:

To page through everything, increment offset by limit until the result array is empty.