Rate Limits & Retries

Limits

Limit	Value
Requests per organization	300 per 60 seconds
Contacts per request	50
Request body size	1 MB (decoded JSON)

The 300-requests-per-minute limit applies per organization (i.e., per API key), not per IP address — and it's shared across every endpoint you call, not tracked separately per route. There's also a defensive per-IP limit to protect the platform from a single misbehaving client — you shouldn't hit it under normal use.

Handling a 429

If you go over the limit, you'll get:

{
  "request_id": "req_...",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests — please retry later"
  }
}

HTTP status 429, with a Retry-After header telling you how many seconds to wait before trying again.

Batch instead of looping

If you're sending contacts one at a time in a loop against POST /api/v2/contacts, you'll burn through the limit fast. Since POST /api/v2/contacts/batch carries up to 50 contacts per request, switching to it is almost always the better approach if you're syncing more than a handful of contacts at once.

Retrying failed requests

Status	Should you retry?
429 (rate limited)	Yes — wait for the Retry-After duration, then retry
500, 502, 503, 504	Yes — with exponential backoff
Any other 4xx	No — the request itself needs to be corrected first

A note on retry safety

This API doesn't currently support an idempotency key for exact-replay guarantees — if a request times out and you retry it, you might get a slightly different response the second time (rather than a byte-identical copy of what the first attempt would have returned). In practice this rarely matters:

• Retrying a create is safe. If the first attempt actually succeeded, the retry will correctly report the contact as a duplicate (DUPLICATE_EMAIL) instead of creating a second copy — contacts are never duplicated by a retry.
• Retrying an update (with overwrite: true) is safe. If the first attempt's changes already went through, the retry will report unchanged rather than reapplying anything.

So while you won't get an identical response replayed back to you, retrying is always safe from a data-correctness standpoint — you'll never end up with duplicate contacts or a corrupted record from a retry.

What's next

• Create or Update a Contact — single-contact endpoint
• Sync a Contact Batch — batch endpoint
• Error Codes