Retry a create safely
Every POST needs an Idempotency-Key, so a request you retry after a timeout can never create the same patient, visit or invoice twice.
A create that times out may have worked. Send every POST with an Idempotency-Key header, and if you retry, send the same key with the same body:
curl -X POST https://dashboard.practor.app/api/v1/patients \
-H "Authorization: Bearer $PRACTOR_API_KEY" \
-H "Idempotency-Key: 2f1c7a52-8f0e-4c1b-9d7e-0b6a3f4e8c21" \
-H "Content-Type: application/json" \
-d @patient.jsonA POST without the header is refused with a 400 that names Idempotency-Key in errors. Use a new UUID for each record you create, and keep it with the record in your own system until the create has succeeded.
What a retry gets back
| You send | You get |
|---|---|
| The same key and the same body, after the first request finished | A 201 with the record the first request created, as it is now, and the header Idempotent-Replayed: true, which tells you this answer is a repeat. Nothing new is created. If that record has since been deleted, you get a 404. |
| The same key while the first request is still running | 409. Wait a moment and retry. |
| The same key with a different body | 422, with the code idempotency_key_reused. You've given two different requests the same key, and Practor won't guess which one you meant. |
A key is remembered for 24 hours, per client. Two clients can use the same key without meeting. If a create is cut off halfway, so the first request never finished, the key is freed after two minutes and a retry creates the record.
Updates (PUT) don't need the header: sending the same whole resource twice leaves it the same.