Skip to main content

Idempotency

Every POST 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:
If the network times out and you retry with the same key and body, you get the same response — no duplicate lead is created.

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 all POST 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.