Idempotency

On a fulfillment rail, a retried request is not a harmless duplicate — it can be a second physical shipment of a compounded drug. So every mutating request accepts an Idempotency-Key, and neolife guarantees a given key acts at most once.

How it works#

Send a UUID in the Idempotency-Key header on any POST/PATCH/PUT:

curl -X POST https://api.neolife.health/v1/orders/ord_123/submit \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42"

• First call with a key runs normally and its response is stored.
• A retry with the same key and the same body replays the stored response (with Idempotent-Replayed: true) — the action does not run again.
• The same key with a different body returns 409 Conflict. Keys are bound to the exact request they first completed.

Keys must be UUIDs. This is deliberate: it guarantees no patient data can ever be encoded in a key.

Choosing keys#

Derive a stable key from the logical operation, not a random value per attempt — otherwise a retry looks like a brand-new request. A good key for "submit order X" is deterministic in X (for example, a UUIDv5 of submit:ord_123). The SDKs and MCP server do this for you automatically.

Retries and failures#

• If a request fails before it was recorded (a network drop, a timeout), retry with the same key — you'll either complete the action once or replay its result.
• If the original attempt crashed mid-flight, a retry may report that the outcome is indeterminate; verify the resulting state (for example, GET the order) and retry with a new key if needed. neolife errs toward never acting twice over silently re-running.

Why it matters#

Combined with server-side single-dispatch guarantees on order submission, idempotency is what lets integrators and agents retry aggressively without ever double-shipping. Build your client to always send a key.