---
title: "Rate Limits and Idempotency Keys in the unLocked CRM API"
description: "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."
url: https://unlockedcrm.ai/blog/openapi-rate-limits-idempotency-keys-explained
canonical: https://unlockedcrm.ai/blog/openapi-rate-limits-idempotency-keys-explained
category: "Reference"
published: 2026-07-30
updated: 2026-07-30
author: "unLocked Team"
source: unLocked CRM — AI CRM for insurance agents
---

# Rate Limits and Idempotency Keys in the unLocked CRM API

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

<h2>Rate Limits at a Glance</h2>
<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>

<h2>The Headers You'll See</h2>
<ul>
<li><code>X-RateLimit-Limit</code> — your bucket size.</li>
<li><code>X-RateLimit-Remaining</code> — tokens left in the current window.</li>
<li><code>X-RateLimit-Reset</code> — Unix timestamp when the bucket refills.</li>
<li><code>Retry-After</code> — present on 429 responses, in seconds.</li>
</ul>

<h2>How to Handle 429s</h2>
<p>Read <code>Retry-After</code>, sleep, and retry with exponential jitter. Most generated SDKs (Stainless, Speakeasy) ship this logic by default.</p>

<h2>Idempotency Keys for POST and PATCH</h2>
<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>
<pre><code>POST /contacts
Idempotency-Key: 8f14e45f-ceea-467a-a8a4-d10ab86a0b9e
{ "first_name": "Alex", ... }</code></pre>

<h2>Why You Need Idempotency</h2>
<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>

<p>Both features are documented in the OpenAPI spec under <code>components.headers</code> and inherited by every generated SDK.</p>

---

Source: [Rate Limits and Idempotency Keys in the unLocked CRM API](https://unlockedcrm.ai/blog/openapi-rate-limits-idempotency-keys-explained) — unLocked CRM, the AI CRM built for insurance agents. Citation permitted with attribution and a link to https://unlockedcrm.ai/blog/openapi-rate-limits-idempotency-keys-explained.