Idempotency

Every POST requires an Idempotency-Key header. Without one, the request is rejected before the handler runs:

{
  "error": {
    "code": "invalid_request",
    "message": "This endpoint requires an Idempotency-Key header so a retried request can't apply twice. Use a UUID per logical operation.",
    "param": "Idempotency-Key"
  }
}

This is mandatory rather than optional because the failure it prevents is silent: a request that times out in transit has still been applied, and a client that retries without a key creates a second member, a second group, a second charge. Making the key required means a retry is always safe.

Sending a key

Generate one UUID per logical operation — not per HTTP attempt. All retries of the same operation reuse the same key.

curl -X POST https://api.dueflow.co/v1/members \
  -H "Authorization: Bearer $DUEFLOW_TOKEN" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9c6a-9c0b3f39b41c" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}'

What a reused key does

Situation	Result
Same key, same body	The original response is replayed, with `Idempotent-Replayed: true`. Nothing runs a second time.
Same key, different body	`409 conflict`. The key already means something else.
Same key, original request still in flight	`409 conflict`. Wait and retry; the first attempt is still deciding.
Same key, original attempt failed	The key is released, so the retry runs normally.
Same key, more than 24 hours later	Keys expire after 24 hours; the key is reusable.

A replay returns the stored response — the same body and the same status:

HTTP/1.1 201 Created
Idempotent-Replayed: true

{ "id": "S_QZS1bcVIsrxWJHTKbIM", "firstName": "Docs", "lastName": "Example", ... }

Note that it is 201, not 200. The response describes the original operation, not the act of replaying it, so a client can handle both identically.

Keys are scoped to your token

Two tokens can use the same key without colliding. A key from a revoked token carries nothing over to its replacement — after rotating, an in-flight retry runs as a fresh request, so make sure the operation is also naturally deduplicated (a duplicate email returns 409 conflict) if that matters to you.

Body comparison ignores key order

The fingerprint is taken over a canonicalized body: object keys sorted at every depth, undefined dropped. So these are the same request, and the second replays rather than conflicting:

{ "firstName": "Ada", "lastName": "Lovelace" }
{ "lastName": "Lovelace", "firstName": "Ada" }

Without that, any client library that serializes keys in a different order would get a spurious 409 on a legitimate retry.

Don’t reuse a key across different operations, and don’t derive keys from something that repeats — “member-import-row-1” every night will replay yesterday’s response for 24 hours instead of importing today’s row.

Getting started

Core concepts

Guides

Sending a key

What a reused key does

Keys are scoped to your token

Body comparison ignores key order

​Sending a key

​What a reused key does

​Keys are scoped to your token

​Body comparison ignores key order

Sending a key

What a reused key does

Keys are scoped to your token

Body comparison ignores key order