UNB, UNH, UNT, UNZ: Envelope Errors That Break the Whole File
Most people skip the first and last lines of an EDIFACT file as "boilerplate". Yet when an entire interchange is rejected - not just flagged, but bounced wholesale - the cause is usually in exactly those lines.
The four rules that must hold
| Rule | What breaks when violated |
|---|---|
UNZ-1 = actual number of messages | Gateway rejects the interchange as incomplete/corrupt |
UNZ-2 = UNB-5 (interchange control reference) | File looks spliced; duplicate detection and acknowledgements fail |
UNT-1 = actual segment count of the message (UNH and UNT included) | Message rejected as truncated |
UNT-2 = UNH-1 (message reference) | Pairing breaks; some gateways drop the message silently |
Nested and orphaned messages
A second UNH before the first UNT means two messages were concatenated incorrectly - or a generator forgot the trailer. A UNT without a preceding UNH is the reverse symptom. Both are one bad copy-paste away, and both invalidate everything between them.
The syntax identifier trap
UNB-1 declares the character set / syntax level (VDA commonly uses UNOA or UNOB). Declaring UNOA and then including characters outside that set produces files that parse on your screen and fail at the gateway.
Version mismatches
UNH carries the message version (e.g. D:20B). Sending a different release than the guideline specifies usually still parses - but the partner's mapping may read different element positions and silently misinterpret your data. A warning here deserves attention, not a shrug.
Why hand-editing is dangerous
Every hand edit shifts the segment count. Fix a date in a text editor and your UNT-1 is instantly wrong unless you also recount - which nobody does reliably. The safe loop is: edit, re-validate the envelope, then send. Our validators check the envelope first, exactly because a broken envelope makes every other check meaningless.