
EDI Error Handling for Container Depots: A Practical Guide
EDI error handling comes down to four jobs: find the exact failed message, work out which layer broke (transport, syntax, mapping or business rules), fix the data at its source, and resend only after you know what happened to the original. For a depot, the stakes are concrete. A gate-in report that never reaches the shipping line, or reaches it wrong, can leave a box showing as unavailable, hold up a release or start a billing dispute. The depots that cope best treat errors as a daily workflow with owners and deadlines, not as a one-off emergency. Our platform supports EDI integrations with shipping line systems and digitizes gate-in/out, so the data starts clean. This guide covers the routine either way.
TL;DR
- Classify every failure first: transport (the file never arrived), syntax (the file cannot be read), or business (the file is well formed but breaks a partner rule). Each has a different owner and fix.
- Read the acknowledgment before you touch anything. A rejection tells you the position and type of the error. Silence is its own alarm.
- Never resend until you know what happened to the original. A blind retry is how duplicate gate moves and double invoices are born.
- Fix the source record, not just the outgoing file, or the same error returns on the next message.
- Set deadlines per message type, because a correction that arrives after the line has acted on the wrong data costs more than the error itself.
Table of Contents
- What counts as an EDI error in a depot
- Step 1: Identify the exact failed message
- Step 2: Read the acknowledgment
- Step 3: Decide which layer failed
- Step 4: Fix the cause where it lives
- Step 5: Resend without creating duplicates
- Step 6: Verify the fix across the whole chain
- Prevent the repeat: validation, monitoring and aging
- Why the source data decides your error rate
- Where ContainerHub fits
- Our perspective
- FAQ
- Sources
What counts as an EDI error in a depot
An EDI error is anything that stops a message from being delivered, read, processed or accepted as intended. In depot work the messages are usually gate-in and gate-out reports, container status updates, and repair estimates and approvals exchanged with shipping lines. Our guide to CODECO EDI for empty container depots covers what lines expect in those messages. Whatever the standard (EDIFACT is common in container work, X12 in US retail and trucking), the failures fall into the same families.
The US retail guideline from the RVCF, an industry group for retail vendors, splits errors into two kinds. In its business process guideline for digital communications and EDI, technical errors are syntax errors: the file does not meet the technical specification and cannot be translated into a usable format. Business errors are the opposite: the data is properly formed but breaks a trading partner’s rules, such as a wrong PO number or a required element the standard itself does not make mandatory.
Translate that to a depot and you get a useful split:
| Layer | What it looks like at a depot | Typical cause |
|---|---|---|
| Transport | The line never receives your gate report | Expired certificate, changed firewall rule, failed file transfer |
| Syntax | The line’s translator rejects the file | Bad delimiter, missing required element, wrong segment order |
| Mapping | The file is valid but fields hold the wrong content | Outdated map, wrong source field, unit or code mismatch |
| Business | The file is accepted but the line’s rules reject it | Unknown booking or release reference, container number not expected, wrong depot code |
| Application | The line’s own system fails to post it | Internal processing failure on the receiver’s side |
The table is our synthesis of the two RVCF categories plus the transport and application layers around them. Its purpose is practical: it tells you who to call.
Step 1: Identify the exact failed message
Start with the business event, not the file. “The EDI is broken” is not a diagnosis. “Gate-out for one container at one depot, sent at a specific time, to one shipping line” is.
Capture at minimum:
- The partner and message type (gate-in, gate-out, status, estimate).
- The container number and the gate transaction it came from.
- The interchange and message control numbers, plus the timestamp.
- The current status: sent, acknowledged, rejected, or no response.
Where it goes wrong: teams search by container number in the depot system and by filename in the transfer log and never connect the two. If the gate transaction and the outbound message live in different tools, every investigation starts with a manual match. When gate activity and EDI sit in one platform, as they do in our gate management software for depots, that match is already made.
Step 2: Read the acknowledgment
Acknowledgments are the receiving system’s own account of what happened. In X12, the functional acknowledgment (997) is the main one. The RVCF guideline says the 997 is created automatically by the partner’s translator and shows the transaction was received and either accepted, rejected for syntax errors, or accepted with errors the translator identified but still processed. When a message is rejected, the acknowledgment points to the position of the bad data, a code for the type of error, and a copy of the data in error.
Two details matter in practice:
- Some systems stop at the first error and others keep going. The same guideline notes both behaviors. Fixing the one error you were shown and resending can therefore trigger a second rejection. Check the whole message against the partner’s specification before retrying.
- “Accepted with errors” is not “fine.” For that status, the RVCF guideline says to contact the partner and ask whether a new transaction is expected.
The guideline also describes the 824 Application Advice as the transaction built for business-error notification. It adds that it is not widely used and that its code list is long, with ambiguous or duplicate codes. If your partner does not send one, a business rejection may only appear as a phone call, an email or a missing status. In EDIFACT, which many shipping lines use, the equivalent roles are played by syntax and application response messages. Confirm in each partner’s implementation guide what they send back.
Silence is a signal. If you sent a message and no acknowledgment arrived within the partner’s normal window, treat it as an open exception, not as a success.
Step 3: Decide which layer failed
Work from the outside in, so you never debug a map when the real problem is an expired certificate.
- Transport. Did the file leave and arrive? Check connection logs, certificate expiry dates, credentials and any recent network or firewall change.
- Envelope and syntax. Did the partner’s translator read it? Look for the acknowledgment status and its error codes.
- Mapping. Is the content in the right fields? Compare a failed message against the partner’s current specification, and ask whether anyone changed a map recently.
- Business rules. Is the data valid but unacceptable? Check references, codes and agreed rules for that partner.
- Application. Did the receiver’s system fail after accepting the file? Only the receiver can confirm this.
A change to a map that went live without full regression testing is a common culprit for suddenly failing messages. Before blaming the partner, ask who touched what in the last week.
Step 4: Fix the cause where it lives
The RVCF guideline is blunt about this: correct bad data in the original source, then reprocess it through the business application and the translator. Do not patch the outgoing file or bury a workaround in a pre-processing routine.
In a depot this has a simple meaning. If a container number was mistyped at the gate, correct the gate record. If a damage code was mapped to the wrong value, correct the mapping. If a depot code was set up wrongly for one line, fix the partner profile. Fixing only the file means the next message from the same source fails the same way.
Who owns each fix is worth writing down once:
| Failure | Usual owner |
|---|---|
| Connectivity, certificates | IT or integration team |
| Syntax, specification mismatch | EDI analyst or mapper |
| Wrong field content | Whoever maintains the map |
| Wrong gate or inspection data | Depot operations (gate or inspection staff) |
| Rejected by the line’s business rules | Depot operations, with the line’s EDI contact |
Our article on exception management for container depots goes deeper on assigning exceptions to the right person.
Step 5: Resend without creating duplicates
This is the step that costs depots the most. A retry feels like progress, but if the first message actually arrived and only the acknowledgment was late, the second one can create a duplicate gate move, a duplicate status or a duplicate invoice.
Use this decision logic:
- The file never reached the partner. Retry the transfer.
- The partner rejected the message. Correct it and resend following that partner’s rules.
- Your own system rejected it before sending. Fix it and reprocess internally.
- You are not sure whether it posted. Confirm with the partner before sending anything.
Control numbers need a policy too. The RVCF guideline says a rejected ship notice should in most cases be fixed and retransmitted with different control numbers, so the two attempts can be tracked, and that retailer rules differ on whether the shipment ID is reused or a replacement flag is needed. The lesson for depots: do not guess. Ask each shipping line whether a correction should replace the original or be sent as a new message, and write the answer into that partner’s profile.
Timing matters as well. The same guideline stresses resending before the shipment arrives. For a depot, the equivalent deadline is whatever point the line starts acting on your data: a release, a status-driven booking, an invoice cycle. Set that cutoff per message type.
Keep an audit trail for every resend: the original control number, the error reason, the correction, who approved it, the new control number and the partner’s final response. It turns the next dispute from an argument into a lookup.
Step 6: Verify the fix across the whole chain
A message is not fixed because the transfer log says “sent.” Confirm four things: the file was delivered, the acknowledgment shows acceptance, the partner’s system shows the right status, and the downstream outcome is right (the container shows the correct status at the line, the invoice matches). A successful send does not repair a wrong value inside the message.
Prevent the repeat: validation, monitoring and aging
The RVCF guideline argues that, ideally, a document that fails the standard’s specification never leaves the sender’s system. Use your translator’s validation on outbound data, and add partner-specific checks for business rules, such as required references and code lists. NIST’s older but still relevant guidelines for evaluating EDI products make a related point: a product should help users learn more about an error and its likely solution, and let the user choose whether an erroneous transaction passes and processing continues or halts with a diagnostic message. Decide that behavior deliberately for each message type. Halting suits invoices. Passing and flagging may suit low-risk status updates.
A lightweight monitoring routine for a depot:
- Daily: review every message with no acknowledgment past the partner’s normal window, and every rejection.
- Per rejection: log the layer, cause and owner.
- Weekly: count errors by cause and by partner. Three rejections from the same field mean a mapping or data-entry problem, not bad luck.
- On every map or partner change: run test messages against the partner’s current specification before going live.
The weekly count is where prevention happens. If most errors trace back to manual keying at the gate, the answer is upstream.
Why the source data decides your error rate
Most business errors begin before any message exists: a container number typed from a paper interchange form, a damage description written by hand and re-entered later, a repair estimate keyed twice. Each re-entry is a chance for a mismatch the line’s system will reject. Our guide to EDI integration for depot systems and our piece on the role of EDI in depot operations cover how gate, inspection and repair data feed the messages. The same logic applies to billing, which is why the ERP integration guide warns about batch exports that hide errors until month end.
Where ContainerHub fits
ContainerHub is a cloud platform for empty container depots that digitizes gate-in/out, inspections, repair workflows and billing, and supports EDI integrations with shipping line systems. Because those activities share one record, the data behind your messages is captured once at the gate, not re-keyed from paper. It also includes a client portal for self-service visibility, so customers can check status themselves.
Plans are published on the pricing page: Free at $0 per month, Starter at $199 per month, Growth at $499 per month and Enterprise from $999 per month. If EDI is your priority, start with our page on container depot software with EDI.
Our perspective
Every depot we talk to describes EDI errors as a connectivity problem. Most of them are data problems that show up as connectivity problems, because the first anyone hears of a bad gate record is a rejection from a shipping line.
Our view is that error handling begins at the gate. If gate-in, damage inspection, repair approval and billing are digital and connected, the container number, the condition and the status are entered once and reused everywhere. That is the idea behind a unified depot platform with configurable workflows: fewer places for a typo to enter, and one record to correct when something does go wrong.
We also believe depots should not need an integration specialist to understand why a message failed. Exceptions should have a clear owner and a visible status, and the people at the gate and in the office should see the same picture the line sees. That is what we are building toward, with AI assistance inside the workflow and direct support behind it.
William Carley
FAQ
What is the first thing to check when an EDI message fails?
Identify the exact transaction: partner, message type, container, control numbers and timestamp. Then read the acknowledgment, if there is one. It usually tells you whether the problem was syntax, content or a business rule, which decides who fixes it.
Should I resend a rejected EDI message right away?
Only after you know what happened to the original and have fixed the cause. If the first message may have posted, a resend can create a duplicate. For corrections, ask the partner whether to reuse the original references or send the message as new, and whether control numbers should change.
What is the difference between technical and business EDI errors?
Technical errors are syntax problems: the file does not meet the specification and cannot be translated. Business errors occur when the file is well formed but breaks the partner’s rules, such as a wrong reference or a missing element they require. Technical errors can be caught by validation before sending. Business errors need partner-specific checks.
What does a missing acknowledgment mean?
It means the message is unconfirmed, not successful. Either the file never arrived, the partner’s system has not processed it, or the acknowledgment was lost. Check transport logs first, then contact the partner before retrying.
How can a depot reduce EDI errors over time?
Track errors weekly by cause and partner, correct the source data and maps instead of single files, and test every change against the partner’s current specification. Capturing gate and inspection data digitally, once, removes many of the re-entry mistakes that cause rejections.
Sources
- RVCF Business Process Guideline for Digital Communications and EDI (2023)
- NIST Special Publication 500-231, Guidelines for the evaluation of electronic data interchange products