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/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