EHR and clinical API integrations fail in specific, nameable ways
Problem · Clinical Interoperability
FHIR and HL7 v2 integrations fail through a bounded set of specific mechanisms, and for SMART on FHIR REST APIs certified under ONC §170.315(g)(10) against US Core 3.1.1, each one (auth-token expiry storms, resource-version drift, silent partial writes, mishandled ACK/NACK codes) needs its own retry handling and error containment in HealthTech integrations.
How do EHR and clinical API integrations fail?
FHIR and HL7 v2 integrations fail through a bounded set of specific mechanisms: auth-token expiry storms, resource-version drift, silent partial writes, and mishandled ACK/NACK codes. Each one needs its own retry handling and error containment.
"The integration is flaky" is not a diagnosis. FHIR and HL7 v2 integrations fail through a small set of specific, recurring mechanisms — auth-token expiry storms, resource-version drift, silent partial writes, mishandled ACK/NACK codes — each with a distinct root cause and a distinct fix. Naming the actual mechanism is what turns a recurring incident into a closed one.
"Flaky" is where root-cause analysis stops too early
A clinical integration team that logs "EHR integration flaky again" as an incident summary hasn't found a root cause — it's found a symptom. FHIR and HL7 v2 integrations fail through a bounded set of specific mechanisms, each checkable and each with a distinct fix.
Direct protocol handling over an abstraction that hides failure
A common failure amplifier: an EHR-vendor SDK or integration-engine abstraction that hides the underlying FHIR/HL7 protocol behavior "for convenience," including hiding exactly which failure occurred. Handling the wire protocol directly — parsing the actual ACK/NACK code, checking the actual FHIR response status and `OperationOutcome` — surfaces the specific failure mode instead of a generic "request failed" the abstraction collapsed six different real failures into.
Six specific failure modes
| Failure mode | Root cause | Mitigation |
|---|---|---|
| Auth-token expiry storm | All clients refresh reactively at the same TTL boundary | Refresh ahead of expiry with jitter |
| FHIR resource-version drift | Missing version-aware (If-Match) update | Enforce conditional updates; reject on mismatch |
| Silent partial write | Multi-resource transaction not atomic | Use FHIR transaction bundles; verify full-bundle success |
| HL7 v2 ACK/NACK mishandled | Timeout or NACK treated as success | Explicitly parse ACK/NACK/AE; timeout is its own failure state |
| Terminology mismatch | Different code-system versions in use across systems | Pin and record terminology version per integration |
| Pagination truncation | Client doesn't follow the bulk-export next link to completion | Verify against expected count, not just "no error" |
Engineering reference only. Not formal regulatory counsel. Failure modes listed are common, not exhaustive — scope to your own integration's actual interfaces.
Artifact: ehr-api-integration-failure-modes.md
Generated client-side; no server round-trip, no account required.
# EHR / Clinical API Integration Failure Modes (FHIR/HL7) — Reference Table (v1.0.0)
Engineering reference only. Not exhaustive; scope to your own integration's
actual failure surface.
| Failure mode | Symptom | Root cause | Mitigation |
|---|---|---|---|
| Auth-token expiry storm | Bulk 401s across many concurrent requests near token TTL boundary | No proactive refresh; all clients refresh reactively at once | Refresh ahead of expiry with jitter; short-circuit retry storms |
| FHIR resource-version drift | Silent overwrite of a concurrent edit | Missing `If-Match` / version-aware PUT | Enforce conditional updates; reject on version mismatch, don't merge silently |
| Silent partial write | Downstream system shows incomplete record, no error surfaced | Multi-resource transaction not atomic; partial batch succeeded | Use FHIR transaction bundles; verify full-bundle success before considering the write complete |
| HL7 v2 ACK/NACK mishandled | Message assumed delivered when it was rejected | ACK not parsed / timeout treated as success | Explicitly parse ACK/NACK/AE codes; timeout is a distinct failure state, not success |
| Terminology mismatch | Code maps to wrong concept across systems | Different code system versions (e.g. SNOMED CT release) in use | Pin and record the terminology version per integration; validate on ingest |
| Pagination truncation | Bulk export appears complete but is missing records | Client doesn't follow `next` link to completion | Verify export completion against expected count or a terminal marker, not just "no error" |
Provenance & review state
- Last reviewed
- Sources
-
- HL7 FHIR R4 — Health Level Seven International
- ONC Health IT Certification Criteria — Office of the National Coordinator for Health Information Technology
- Ingested from
-