Configuring htmx hx-retry to Avoid Duplicate Writes on POST Requests

The hx-retry attribute cannot be configured to stop based on custom success headers, nor does htmx provide a declarative way to inject unique idempotency tokens for retries. Because htmx re-issues the exact same request, server-side deduplication is the only recommended approach to prevent duplicate writes during POST operations.

The Mechanism of hx-retry

When hx-retry is triggered (typically by 500, 503, or 504 error codes), htmx repeats the original AJAX request. If a network timeout occurs after the server has successfully processed the write but before the client receives the response, the subsequent retry will result in a duplicate resource unless the server can recognize the request as a duplicate.

Implementation Strategy: Idempotency Keys

To ensure a POST request is processed only once, you must implement an idempotency pattern. Since htmx does not automate this, you must handle the token generation manually:

1. Generate a Client-Side UUID: Create a unique identifier when the form is rendered or just before submission.
2. Include the Token: Pass this ID as a hidden input field or a custom HTTP header.
3. Server-Side Validation: The server should check if the token has already been processed. If it has, the server should return the original successful response (or a 200 OK) without executing the write logic again.

<form hx-post="/create-resource" hx-retry="3s,3">
  <input type="hidden" name="idempotency_key" value="uuid-1234-5678">
  <button type="submit">Submit</button>
</form>

Verification Steps

To verify your deduplication logic is working correctly:

• Open the browser Network tab.
• Simulate a transient failure (e.g., using a proxy to return a 503 error) on the first attempt.
• Confirm that the second request contains the same idempotency_key.
• Verify in your database that only one record was created despite multiple requests.

Diagnostic Detail Required

Are you generating the idempotency token on the server during page render, or via JavaScript immediately before the htmx:configRequest event? This determines whether a page refresh would reset the token and potentially allow a duplicate write across different sessions.