Safe retries with Idempotency-Key in the Hi Doctor API

key="$(uuidgen)"  # store it with the pending operation before the first attempt
curl --silent --show-error --max-time 30 --request POST \
  "$HD_BASE_URL/v1/users/conversations/$HD_CONVERSATION_ID/messages/" \
  -H "Authorization: Bearer $HD_ACCESS_TOKEN" \
  -H "X-Brand-Slug: hi-doctor" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $key" \
  --data @message.json

import os
import uuid
import requests

base = os.environ["HD_BASE_URL"].rstrip("/")
headers = {
    "Authorization": "Bearer " + os.environ["HD_ACCESS_TOKEN"],
    "X-Brand-Slug": "hi-doctor",
    "Accept": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),  # persist with the pending operation
}
url = base + "/v1/users/conversations/" + os.environ["HD_CONVERSATION_ID"] + "/messages/"
body = {"content": "Message text written by the patient"}

for attempt in range(3):
    try:
        response = requests.post(url, json=body, headers=headers, timeout=30)
    except requests.Timeout:
        continue  # same key, same body: the message is sent at most once
    if response.status_code == 409 and response.json().get("code") == "idempotency_in_progress":
        continue  # still running: wait, then retry with the same key
    break
replayed = response.headers.get("Idempotent-Replayed") == "true"

import { randomUUID } from "node:crypto";

const base = process.env.HD_BASE_URL.replace(/\/$/, "");
const key = randomUUID(); // persist with the pending operation
const url = `${base}/v1/users/conversations/${process.env.HD_CONVERSATION_ID}/messages/`;
const body = JSON.stringify({ content: "Message text written by the patient" });

let response;
for (let attempt = 0; attempt < 3; attempt++) {
  try {
    response = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.HD_ACCESS_TOKEN}`,
        "X-Brand-Slug": "hi-doctor",
        Accept: "application/json",
        "Content-Type": "application/json",
        "Idempotency-Key": key,
      },
      body,
      redirect: "error",
      signal: AbortSignal.timeout(30000),
    });
  } catch {
    continue; // timeout or network error: retry with the same key
  }
  if (response.status !== 409) break;
}
const replayed = response?.headers.get("idempotent-replayed") === "true";