Skip to main content
Network calls fail in the worst way: you send a POST, the connection drops, and you don’t know whether it landed. Idempotency keys make the retry safe.

​
How to use it

Send an Idempotency-Key header — any unique string you generate (a UUID is ideal) — on a mutating request:
If you send the same key again, Duro replays the original response — same status, same body — instead of creating a second subscription.

​
How it works

  • Keys are scoped per tenant (@@unique([tenantId, key])) — your keys can’t collide with another merchant’s, and they can’t be probed across tenants.
  • Reuse a key only for the same logical operation. Reusing it for a different request is a client bug; the stored response won’t match what you expect.
  • Use a fresh key per distinct intent — typically a UUID per user action.

​
When you don’t need it

GETs are naturally idempotent — no key needed. Some operations are idempotent by design regardless: paying a completed checkout session returns the completed result without re-charging, and creating a renewal invoice is guarded by a per-period unique key in the database. But for your own POSTs, an Idempotency-Key is the simplest way to make retries safe.