htmx hx-post retry configuration for non-idempotent form submissions

Answer the Question First

1. Stable idempotency key: generate the key once per page load (or first submit) in JavaScript, store it in a global variable or a hidden input, and add it to every hx-post with hx-headers or via an htmx:configRequest listener. The same key is sent on every retry because it is not re‑generated.

2. Disabling the trigger: use the htmx:beforeRequest event to call elt.setAttribute("disabled", "disabled") or elt.disabled = true. This prevents double‑clicks. It does not block an intentional retry because a retry can first re‑enable the element (e.g. elt.disabled = false) or trigger the request programmatically with htmx.trigger(elt, "submit"), which bypasses the disabled state.

3. When to retry: retry on htmx:sendError (network failure, no response) and, if the server guarantees idempotency, also on htmx:responseError for 5xx responses. Do not retry 4xx responses; they indicate a client error that will not succeed on repeat.

How to Implement It

1. Generate the key (once per page load):

   const idempotencyKey = crypto.randomUUID();
   // Store in a hidden input for easy access by htmx
   const hidden = document.createElement("input");
   hidden.type = "hidden";
   hidden.name = "Idempotency-Key";
   hidden.value = idempotencyKey;
   document.querySelector("form").appendChild(hidden);
   

2. Attach the key to every request via hx-headers or htmx:configRequest:

   <form hx-post="/orders" hx-headers='{"Idempotency-Key": "${idempotencyKey}"}'>
     …
   </form>
   

   Because the variable is evaluated only once, the header stays the same on retries.

3. Disable the submit button to avoid double‑clicks:

   document.querySelector("form").addEventListener("htmx:beforeRequest", (e) => {
     e.target.querySelector("button[type=submit]").disabled = true;
   });
   

4. Retry logic – listen for htmx:sendError (or htmx:responseError if you trust idempotency on 5xx):

   const maxRetries = 3;
   let attempt = 0;
   
   function retry(elt) {
     if (attempt >= maxRetries) return;
     attempt++;
     // Optionally re‑enable the button for a retry
     elt.querySelector("button[type=submit]").disabled = false;
     // Back‑off: 500ms, 1000ms, 2000ms …
     setTimeout(() => htmx.trigger(elt, "submit"), 500 * Math.pow(2, attempt-1));
   }
   
   document.querySelector("form").addEventListener("htmx:sendError", (e) => retry(e.target));
   

5. Server‑side deduplication (must be implemented separately): store the idempotency key in a unique column. On a duplicate key, return the original response instead of performing the write again.

Key Take‑aways

• Generate the idempotency key once; keep it in a variable or hidden field so retries reuse it.
• Disable the submit button in htmx:beforeRequest; re‑enable it before a programmatic retry.
• Retry only on htmx:sendError for network failures; 5xx can be retried only if the server guarantees idempotency.
• Always enforce deduplication on the server; client‑side retry alone cannot prevent duplicate writes.

Missing Diagnostic Detail

Does your backend already enforce idempotency (unique constraint on the key) or will you need to add that logic?