When to Retry

Retry logic is typically necessary in the following situations:

• Network interruptions that cause timeouts or dropped connections
• Temporary server errors, such as 502 Bad Gateway or 503 Service Unavailable
• 202 Accepted responses in asynchronous workflows, indicating the request is still being processed

You should not retry in cases of:

• 4xx client errors that indicate a malformed request or invalid input
• 409 Conflict responses returned due to a reused idempotency key with a different payload
• Explicit errors such as Patient Not Found, which require intervention or updated input

How to Implement Retries

To support safe retries:

• Include the HG-Idempotency-Key header with all POST requests. Use a UUIDv4 value that is unique per request payload.
• Honor retry delays by implementing exponential backoff with jitter. This prevents thundering herd behavior and aligns with rate-limiting controls.
• Log and correlate requests using X-HG-Request-ID and your internal transaction ID to trace execution across retries.
• Evaluate response status before retrying. For asynchronous workflows, use the polling endpoint or webhook notifications rather than re-POSTing the original request.

Duplicate Detection and Conflict Handling

Health Gorilla’s infrastructure identifies duplicate requests using the HG-Idempotency-Key:

• Identical payloads with the same key return the original response and are safe to retry.
• Different payloads with the same key return 409 Conflict. This prevents accidental updates or data corruption.

For asynchronous jobs, duplicate POST submissions with the same key will return the same job reference until the job completes or expires.

Practical Considerations

• Retry logic should be isolated per endpoint. Some endpoints support polling, others require client-side timeouts.
• Avoid re-submitting high-impact requests (such as DocumentReference or Patient updates) without a clear resolution path.
• If a retry is successful but the response is unclear, query the resource by identifier rather than guessing the result.

Summary

Effective retry handling reduces the risk of data duplication, improves reliability across network conditions, and supports consistent behavior in both synchronous and asynchronous workflows. By using idempotency keys, monitoring response codes, and controlling retry timing, you can safely recover from transient failures without compromising data integrity.