When an HL7v2 message is received, extract MSH-3 (sending application), MSH-4 (sending facility), MSH-5 (receiving application), MSH-6 (receiving facility), MSH-10 (message control ID), and MSH-12 (version ID) from the inbound message
Construct the ACK MSH segment: swap sending and receiving application/facility pairs so MSH-3/MSH-4 reflect your application as sender and MSH-5/MSH-6 reflect the original sender as the target; set MSH-7 to the current timestamp and MSH-9 to ACK^A01 (or the appropriate trigger if using enhanced mode ACK)
Build the MSA segment: MSA-1 is the acknowledgment code (AA for application accept, AE for application error, AR for application reject), MSA-2 is the message control ID copied exactly from the inbound MSH-10
For AE responses, add an ERR segment specifying the error location using HL7 error location notation (segment ID, sequence, field position), the HL7 error code from Table 0357, and a human-readable error text in ERR-7 to help the sender diagnose the problem
Use AR (application reject) only for structural problems that make the message unprocessable (e.g., unsupported message type, missing required MSH fields); use AE for business-logic failures that the sender may be able to correct and resubmit
Send the ACK immediately upon receipt acknowledgment, not after business processing completes; if business processing is asynchronous, ACK the transport receipt and use a separate mechanism (query response or notification) to convey processing results
Known gotchas
The distinction between AA, AE, and AR has operational consequences: AA tells the sender to remove the message from its retry queue; AE and AR may trigger immediate retry or error alerting depending on the sender's configuration — use the correct code for the situation
Some older HL7v2 implementations do not parse the ERR segment and rely solely on MSA-3 (free text error) for human-readable error information; populate both MSA-3 and ERR-7 for compatibility with legacy senders
Enhanced acknowledgment mode (defined in MSH-15 and MSH-16) specifies whether commit-level and application-level ACKs are required separately; most modern interfaces use original mode (single ACK) but verify with your trading partner
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp