Rate limits

API requests are rate-limited. Three windows apply simultaneously, and the same limits apply to every endpoint — reads and writes alike.

The limits

Window	Limit
Per second	10 requests
Per minute	100 requests
Per hour	1,000 requests

Exceeding any one of them returns 429 Too Many Requests.

Limits are counted per client IP address, not per API key. If several of your systems share an outbound IP, they share a single budget. Conversely, spreading traffic across hosts gives each its own.

Rate limit headers

Every response reports your standing in all three windows. Header names carry the window as a suffix:

Header	Meaning
`X-RateLimit-Limit-short`	Requests allowed in the 1-second window.
`X-RateLimit-Remaining-short`	Requests left in it.
`X-RateLimit-Reset-short`	When it resets.
`X-RateLimit-Limit-medium`	The same three, for the 1-minute window.
`X-RateLimit-Limit-long`	The same three, for the 1-hour window.
`Retry-After-short` / `-medium` / `-long`	On a `429` — how long to wait. The suffix tells you which window you tripped.

The suffix matters. There is no unsuffixed X-RateLimit-Remaining or Retry-After — reading those returns nothing. Parse the suffixed names.

When you exceed the limit

You receive 429 with a body explaining the failure. Wait for the window named in the Retry-After-* header, then resume.

Exponential backoff

import time, requests

RETRY_AFTER_HEADERS = ("Retry-After-short", "Retry-After-medium", "Retry-After-long")

def post_with_backoff(url, json, headers, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.post(url, json=json, headers=headers)
        if resp.status_code != 429:
            return resp
        wait = next(
            (float(resp.headers[h]) for h in RETRY_AFTER_HEADERS if h in resp.headers),
            2 ** attempt,
        )
        time.sleep(wait)
    raise RuntimeError("rate limited after retries")

Designing within the limits

Don’t sync by polling. Instead of re-fetching all contacts hourly, push changes as they happen with events.
Mind the hourly ceiling. 1,000 requests per hour is the binding constraint for backfills — averaging under one call every 3.6 seconds. A job that respects the per-second limit can still exhaust the hour.
Batch your backfills. For large one-time contact imports, the dashboard’s CSV import avoids the API entirely and is the better tool.
Queue on your side. Put API calls on a job queue with retry and backoff rather than calling inline from request handlers.
Watch X-RateLimit-Remaining-long and slow down before it reaches zero — it beats reacting to 429s.

Getting started

API reference

Events & webhooks

Build integrations

The limits

Rate limit headers

When you exceed the limit

Designing within the limits

​The limits

​Rate limit headers

​When you exceed the limit

​Designing within the limits

The limits

Rate limit headers

When you exceed the limit

Designing within the limits