Rate Limits and Idempotency Keys in the unLocked CRM API

How our token-bucket rate limiter works, what the X-RateLimit headers mean, and why every POST/PATCH should send an Idempotency-Key in production.

Two features separate hobby APIs from production-grade ones: visible rate limits and idempotency keys. Both are first-class in unLocked CRM.

Rate Limits at a Glance

Each API key gets a token-bucket allowance: 600 requests per minute on the standard tier, 3,000/min on Pro, and custom on Enterprise. Bursts up to 2× the steady-state rate are allowed.

The Headers You'll See

  • X-RateLimit-Limit — your bucket size.
  • X-RateLimit-Remaining — tokens left in the current window.
  • X-RateLimit-Reset — Unix timestamp when the bucket refills.
  • Retry-After — present on 429 responses, in seconds.

How to Handle 429s

Read Retry-After, sleep, and retry with exponential jitter. Most generated SDKs (Stainless, Speakeasy) ship this logic by default.

Idempotency Keys for POST and PATCH

Every mutating endpoint accepts an Idempotency-Key header — any string up to 255 chars (UUIDs are conventional). If the same key arrives twice within 24 hours, the second call returns the original response without re-executing the side effect.

POST /contacts
Idempotency-Key: 8f14e45f-ceea-467a-a8a4-d10ab86a0b9e
{ "first_name": "Alex", ... }

Why You Need Idempotency

Network timeouts lie. A 504 doesn't mean the request failed — it means you don't know. Replay with the same key and you'll either get the original success response or, if it really did fail, a fresh attempt. No duplicate contacts, no double-charged commissions, no panicked customer support tickets.

Both features are documented in the OpenAPI spec under components.headers and inherited by every generated SDK.