Idempotency key
An idempotency key is a unique value a client sends with an API request so that if the same request is retried — after a timeout, a crash, or a duplicate webhook — the server performs the action once and returns the same result, which in telehealth prevents duplicate patients, duplicate encounters, and duplicate prescriptions.
- Makes retries safe: one action, one result
- Prevents duplicate encounters and prescriptions
- Key per logical action, stored before sending
- Apply the same idea to webhook event IDs
Why it matters more in healthcare
In most software a duplicate write is a nuisance. In a care pipeline it is a second prescription request in a clinician’s queue, a second charge on a patient’s card, or a second order at the pharmacy. Networks fail exactly often enough that any integration handling real volume will retry, so retries have to be safe by design.
How to use it
- Generate a key per logical action (this patient’s refill request for this cycle), not per HTTP attempt
- Store the key with your own record before sending, so a crash between “sent” and “saved” still retries with the same key
- On webhooks, treat the event ID the same way: record it, skip if seen
- Let keys expire only after the action is unambiguously complete
Idempotency and agents
AI agents retry too — and sometimes re-plan and issue the same request twice. An agent that submits a refill encounter should derive its key from the patient, care plan, and cycle so a re-run cannot create a duplicate. This is one of the guardrails that belongs in infrastructure rather than in the prompt.
Compliance handled, so you can build
Lithos runs the clinicians, pharmacies, and 50-state rules behind your care program — one API.
Frequently asked questions
Where does an idempotency key go?
Typically in a request header on write operations. The server stores the key with the result and returns the stored result for any repeat within the key’s lifetime.
What happens if two different requests share a key?
Well-behaved APIs reject the second with an error rather than silently returning the first result, which is why keys must be unique per logical action.