Skip to main content
The Idempotency-Key header makes retrying a Hi Doctor Partner API consultation submission safe. Within 24 hours, a retry with the same key, path and body returns the stored result instead of creating a second consultation. POST /v1/partner/consultations/ requires the header; other write endpoints do not take it. Last reviewed: 2026-11-04 Networks fail: a submission can reach Hi Doctor while the response never reaches you. After 24 hours the stored result is gone and the request runs again (see Lifetime). This page covers the Partner API only; the patient REST API has its own idempotency rules.

​
Where does an Idempotency-Key apply?

POST /v1/partner/consultations/ requires an Idempotency-Key header. Without it the request fails with 400 idempotency_key_required. Other write endpoints do not take an Idempotency-Key, and not all of them are safe to repeat:
  • A cancel that already succeeded returns 409 not_cancellable and changes nothing, so it is safe to retry.
  • Repeating POST /v1/partner/files/ stores another file with a new upload_id. Use only the upload_id you put in the submission; the extra upload is never attached.
  • In test mode, repeating a test advance to prescription_issued adds another synthetic prescription.

​
How do I choose a key?

  • 8 to 128 characters from A-Z, a-z, 0-9, _ and -. Anything else fails with 400 invalid_idempotency_key.
  • Use a fresh random value, such as a UUID, or a value tied to your order, such as order-8812-submit.
  • Store the key with the order before you send the request, so a retry after a crash uses the same key.
  • Keys are scoped to your partner, the mode and the operation. Rotating your API key does not affect them.

​
What happens on a retry?

The request is compared by its exact path and its whole body (key order and spacing do not matter). The path is compared as sent: /v1/partner/consultations/ and /v1/partner/consultations count as different paths, so retry with the same URL as the first attempt, ideally the form the Partner API reference lists, with the trailing slash.

​
Are errors stored?

Only successful submissions are stored. If the first request failed with a 4xx error, for example 422 invalid_answers, nothing is stored for the key: fix the request and send it again. You can keep the key or use a new one. If Hi Doctor fails while processing, everything the request started is rolled back together, including the stored key, so a retry with the same key runs cleanly.

​
Lifetime

Stored results are kept for 24 hours. A retry after that is treated as a new request. Before retrying a submission that is more than a day old, look it up with GET /v1/partner/consultations/?external_reference= to check whether it was created.

​
Example

Running the same command again returns the same 201 body with Idempotent-Replayed: true.

​
Frequently asked questions

​
Which Partner API endpoints need an Idempotency-Key?

Only POST /v1/partner/consultations/, where it is required. Without it the request fails with 400 idempotency_key_required.

​
How long is an idempotency key remembered?

24 hours. A retry after that is treated as a new request, so look the consultation up by external_reference first.

​
What happens if I reuse a key with a different body?

The request fails with 422 idempotency_key_reuse and nothing runs. Use a new key for a new request.

​
Are failed requests stored under the key?

No. Only successful submissions are stored, so after a 4xx error you can fix the request and send it again with the same key or a new one.

​
Does a trailing slash change the idempotency check?

Yes. The path is compared exactly as sent, so retry with the same URL as the first attempt.

​
Does rotating my API key reset idempotency keys?

No. Keys are scoped to your partner, the mode and the operation, not to the API key.

​
Next steps

Submit a consultation

The full submission contract.

Errors

Every error code and how to recover.
Commercial questions: read the partnership FAQ or write to hello@hi-doctor.ai.