Request Behavior

When you include the HG-Idempotency-Key header:

• If the payload matches a previously submitted request with the same key, the original response is returned
• If the payload differs, the server returns 409 Conflict
• If the original request is still being processed, the server returns 202 Accepted

Header Format

Use a UUID v4 string as the value of the HG-Idempotency-Key header: HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125

Supported Use Cases

• Create a new Patient resource without risk of duplicates if the request is retried
• Submit a clinical document (DocumentReference + Binary) where network timeouts may require resubmission
• Submit a diagnostic order via the placeOrder operation when the client cannot confirm success
• Create a Consent resource with repeatable identity and access fields

Example Scenario

Step 1: Submit the original request

POST /fhir/R4/Patient

Headers:

HG-Idempotency-Key: abc123
Content-Type: application/fhir+json
Authorization: Bearer <token>

Body:

{
"resourceType": "Patient",
"name": [{ "given": ["Jane"], "family": "Doe" }],
"gender": "female",
"birthDate": "1992-03-10"
}

Response:

{
"resourceType": "Patient",
"id": "123456789",
"meta": { "versionId": "1", "lastUpdated": "2025-07-02T13:45:00Z" },
...
}

Step 2: Retry the same request with the same key and payload

Response:

{
"resourceType": "Patient",
"id": "123456789",
"meta": { "versionId": "1", "lastUpdated": "2025-07-02T13:45:00Z" },
...
}

Step 3: Retry the same key with a different payload

Returns:

{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "conflict",
"diagnostics": "Payload conflict for idempotency key: abc123"
}]
}