{"id":"openapi-rate-limits-idempotency","slug":"openapi-rate-limits-idempotency-keys-explained","title":"Rate Limits and Idempotency Keys in the unLocked CRM API","excerpt":"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.","content":"<p>Two features separate hobby APIs from production-grade ones: visible rate limits and idempotency keys. Both are first-class in unLocked CRM.</p>\n\n<h2>Rate Limits at a Glance</h2>\n<p>Each API key gets a token-bucket allowance: <strong>600 requests per minute</strong> on the standard tier, <strong>3,000/min</strong> on Pro, and custom on Enterprise. Bursts up to 2× the steady-state rate are allowed.</p>\n\n<h2>The Headers You'll See</h2>\n<ul>\n<li><code>X-RateLimit-Limit</code> — your bucket size.</li>\n<li><code>X-RateLimit-Remaining</code> — tokens left in the current window.</li>\n<li><code>X-RateLimit-Reset</code> — Unix timestamp when the bucket refills.</li>\n<li><code>Retry-After</code> — present on 429 responses, in seconds.</li>\n</ul>\n\n<h2>How to Handle 429s</h2>\n<p>Read <code>Retry-After</code>, sleep, and retry with exponential jitter. Most generated SDKs (Stainless, Speakeasy) ship this logic by default.</p>\n\n<h2>Idempotency Keys for POST and PATCH</h2>\n<p>Every mutating endpoint accepts an <code>Idempotency-Key</code> 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.</p>\n<pre><code>POST /contacts\nIdempotency-Key: 8f14e45f-ceea-467a-a8a4-d10ab86a0b9e\n{ \"first_name\": \"Alex\", ... }</code></pre>\n\n<h2>Why You Need Idempotency</h2>\n<p>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.</p>\n\n<p>Both features are documented in the OpenAPI spec under <code>components.headers</code> and inherited by every generated SDK.</p>","category":"Reference","featureLink":"/mcp-server","cluster":"mcp-api","date":"2026-11-18","lastModified":"2026-11-18","readTime":"6 min","author":"unLocked Team"}