Idempotency
EveryPOST request to the Journeybee API must include a unique
Idempotency-Key header. Retries with the same key return the cached
response from the first successful attempt, so a network blip or
client retry never creates a duplicate lead, deal, or subscription.
Quick start
Generate a UUID per logical operation and send it with your request:Rules
Key format
- 1–255 characters
- Alphanumeric, underscore, hyphen (
[A-Za-z0-9_-]) - UUIDs recommended — they’re collision-free and easy to generate
- Keys are scoped per company, so two companies using the same key string will not collide
Retention
Each key’s response is cached for 24 hours. After that, the same key becomes fresh again.What to use as a key
Pick a value that uniquely identifies the logical operation the client intends, not the physical HTTP request:- ✅
crm-lead-7841-sync— one key per lead you’re syncing. - ✅ A UUID generated when the user clicked “Save”.
- ❌
Date.now()— changes on every retry, defeats dedup. - ❌ A constant string — every request collides.
Client examples
Node.js
Python
Scope today
Idempotency is required on allPOST endpoints. PATCH and
DELETE are not currently required to carry the header — most PATCH
requests are naturally idempotent (setting a field to the same value
twice has the same effect as once) and DELETE is idempotent by
definition.
Related
- Authentication — API key setup
- Errors — error response shapes