---
updatedAt: 2026-03-20T22:09:56.000Z
agentTools:
  projectIndex: https://developer.healthgorilla.com/llms.txt
---

# Idempotent Requests

Health Gorilla supports idempotent request handling to prevent accidental duplication during network retries or timeouts.

## Idempotency Header

Include a unique UUID v4 in the `HG-Idempotency-Key` header with every `POST` request:

`HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125`

## Server Behavior

* Duplicate payloads with the same key within the idempotency window (typically up to 1 hour) return the original response
* Conflicting payloads with the same key return `409 Conflict`
* If the original request is still being processed, subsequent requests with the same key may receive `202 Accepted`

## 409 Conflict Behavior

If a client reuses an existing `HG-Idempotency-Key` with a different request payload, the server will reject the request with a `409 Conflict` response.

This behavior applies to both STU3 and R4 APIs and ensures the integrity of idempotent operations by preventing conflicting updates.

### Example Scenario

1. A `POST` request is sent with `HG-Idempotency-Key: abc123` and Payload A.
2. The same key `abc123` is later reused with Payload **B** (different content).
3. The server compares the content to the original request and returns:

```http
HTTP/1.1 409 Conflict
X-HG-Request-Id: 15e2305e94845d4d2f3f7796
Content-Length: 0
```

## Best Practices

* Use idempotency keys for all `POST` operations that create or trigger processing of resources
* Generate a new UUID for each unique payload
* Store the UUID with the original request to support safe retries