EDI troubleshooting guide
EDI Error Codes Explained: TA1, 997, and 999 Fixes
Decode the acknowledgment, locate the failed level, correct the source—not just the symptom—and keep the same EDI error from returning.
The short definition
What is an EDI error code?
An EDI error code is a machine-readable status or reason value returned after an electronic data interchange transmission is received and checked. It tells the sender whether the failure occurred at the interchange envelope, functional group, transaction set, segment, or data-element level.
The code is only the starting point. The durable fix depends on the root cause: bad source data, an incorrect map, a mismatched trading-partner profile, an unsupported EDI version, a transport problem, or a downstream application failure.
Important distinction: a successful AS2 MDN proves that a message was delivered at the transport layer. It does not prove that the EDI envelope, transaction, or business content was accepted.
Choose the right layer
TA1 vs. 997 vs. 999: where should you look first?
| Acknowledgment | What it checks | First place to investigate | Typical root cause |
|---|---|---|---|
| TA1 | ISA/IEA interchange envelope | Sender/receiver IDs, qualifiers, control number, delimiters, version, date/time | Partner-profile or envelope-generation setting |
| 997 | Functional group and transaction-set syntax/status | AK1, AK2, AK3, AK4, AK5, and AK9 | Missing/extra segment, sequence, element length, code, or control count |
| 999 | Implementation acknowledgment with detailed syntax/implementation feedback | IK3, CTX, IK4, IK5, and AK9 | Trading-partner implementation-guide rule or data quality mismatch |
| Business ACK | Business acceptance after syntax validation | For example, 855, 824, 277CA, or partner portal | Price, SKU, quantity, location, or other business-rule failure |
A 997 is more informative than a TA1 because it can identify the accepted or rejected functional group and transaction set. In a 997, AK3 reports the segment in error, AK4 identifies the element, AK5 gives transaction-set status, and AK9 gives functional-group status. See the Microsoft 997 acknowledgment reference and Oracle’s 997 overview.
Interchange envelope
Common TA1 error codes and fixes
Read TA104 first: A means accepted, E means accepted with errors, and R means rejected or suspended. Then use TA105 to identify the reason. The exact behavior can vary by translator and partner agreement, so treat the code as a locator and verify against your implementation.
| TA105 | Meaning | What to check | Likely fix |
|---|---|---|---|
| 000 | No interchange error | No envelope correction needed | Continue monitoring the 997/999 or business acknowledgment |
| 001 | ISA13 and IEA02 control numbers do not match | Header/trailer generation and split/merge logic | Regenerate the envelope with one matching control number |
| 004 | Invalid segment terminator | Terminator and suffix bytes; encoding changes in transit | Use the partner-approved delimiter and preserve it through transport |
| 005–009 | Invalid sender/receiver qualifier or ID | ISA05–ISA08 and the partner profile | Align IDs, qualifiers, padding, and test/production routing |
| 014–015 | Invalid interchange date or time | ISA09/ISA10 format and source clock | Correct formatting and timezone/system-clock logic |
| 016–017 | Invalid standards identifier or version | ISA11/ISA12 and partner-supported version | Generate the agreed X12 control standard/version |
| 018 | Invalid interchange control number | ISA13 length, content, and sequence | Correct the generator and persist control-number state |
| 020 | Invalid test indicator | ISA15 and endpoint environment | Use the correct T/P/I value for the agreement |
| 021 | Invalid number of included groups | IEA01 versus actual GS/GE groups | Recount groups during envelope generation |
| 022–024 | Invalid structure, premature EOF, or invalid content | Truncation, missing trailers, malformed GS, file encoding | Restore the complete file and correct serialization/transport |
| 025 | Duplicate interchange control number | Resend behavior and control-number store | Confirm partner policy; generate a new unique control number when required |
| 026–027 | Invalid element or component separator | ISA fixed-length positions and partner delimiter rules | Correct separators and prevent middleware from altering them |
Reference: Microsoft’s X12 TA1 acknowledgment and error-code documentation. Always confirm codes against the licensed X12 standard and your partner agreement.
Transaction and group detail
997 and 999 error codes that solve most investigations
The acknowledgment often gives both a status and a location. Do not stop at R. Follow the loop back to the reported segment and element, then compare the original document with the correct partner implementation guide.
| Code/segment | Meaning | Fast diagnostic | Root-cause fix |
|---|---|---|---|
| AK3/IK3 1 | Unrecognized segment ID | Inspect the named segment and delimiters | Correct the map or accidental data/segment boundary |
| AK3/IK3 2 | Unexpected segment | Compare segment position with the guide | Correct conditional logic or segment sequence |
| AK3/IK3 3 | Mandatory segment missing | Find the required segment before the reported position | Populate source data and map the required segment |
| AK3/IK3 4–5 | Loop or segment exceeds maximum use | Count repeats in the affected loop | Constrain source records and map repetitions |
| AK3/IK3 7 | Segment out of sequence | Compare surrounding segments with the guide | Reorder map output; check optional-loop logic |
| AK3/IK3 8 | Segment has data-element errors | Continue to AK4/IK4 for element position | Fix the specific source field or transformation |
| AK4/IK4 1–2 | Required element missing | Locate the element position and condition | Correct upstream data capture and required-field mapping |
| AK4/IK4 4–5 | Element too short or too long | Measure raw value after transformation | Apply the correct length rule; do not silently truncate business data |
| AK4/IK4 6–7 | Invalid character or code value | Check encoding and the partner code list | Normalize encoding or translate to the accepted qualifier/code |
| AK4/IK4 8–9 | Invalid date or time | Check format, impossible dates, and timezone handling | Repair source validation and format transformation |
| AK5/IK5 A/E/R | Transaction accepted, accepted with errors, or rejected | Use AK2/IK2 to find the transaction control number | Fix only the affected transaction and follow resend policy |
| AK5 3 | ST02 and SE02 do not match | Compare transaction header/trailer control numbers | Correct transaction-set envelope generation |
| AK5 4 | SE01 segment count is wrong | Count ST through SE, inclusive | Recalculate after every map/layout change |
| AK5 7 | Invalid or duplicate transaction control number | Check ST02 and resend history | Fix sequencing/idempotency and coordinate the resend |
| AK9 A/E/P/R | Group accepted, accepted with errors, partially accepted, or rejected | Compare AK902–AK904 counts and each transaction loop | Correct affected transactions or group envelope; do not assume all failed |
| AK9 3–6 | Missing GE, GS/GE control mismatch, count mismatch, or duplicate group number | Inspect GS06, GE01, and GE02 | Correct group-envelope and control-number logic |
Do not resend blindly. A partially accepted group can contain both accepted and rejected transactions. Resending the full group may create duplicates. Identify acceptance at the transaction-set level and follow the partner’s replay rules.
Operational playbook
How to troubleshoot an EDI error in seven steps
- Correlate the complete exchange. Gather the original payload, transport receipt, TA1/997/999, business acknowledgment, partner, timestamp, and ISA/GS/ST control numbers.
- Separate transport from EDI acceptance. Confirm whether AS2/SFTP/API delivery succeeded, then evaluate interchange, group, transaction, and business status independently.
- Start at the outermost failed layer. Fix TA1 envelope issues before investigating transaction content. For a 997/999, read group status, transaction status, then segment/element detail.
- Compare the correct implementation guide. Match partner, document, X12 version, environment, and guide revision. A syntactically valid 856 can still violate a retailer’s ASN rules.
- Trace the error upstream. Decide whether the defect originated in the ERP/WMS/TMS, transformation map, partner profile, transport settings, or receiving application.
- Correct and regression-test. Validate the changed document plus neighboring scenarios—optional fields, repeat loops, multiple line items, special characters, and boundary lengths.
- Resend safely and prevent recurrence. Follow the partner’s control-number and replay policy, monitor the new acknowledgment, then add preflight validation, alerting, and an owner for that error class.
From repair to prevention
How to reduce repeat EDI errors
Validate before transmission
Check syntax, required fields, code lists, control counts, and partner-specific rules before the document leaves your environment.
Monitor missing acknowledgments
An absent 997/999 is itself an exception. Alert on partner- and document-specific acknowledgment SLAs.
Correlate business context
Link the raw EDI error to the order, shipment, invoice, partner, system, and deadline so teams can prioritize business impact.
Version maps and guides
Tie each map to a partner, standard version, environment, and guide revision; regression-test before promotion.
Make control numbers durable
Persist sequence state across restarts and design resends for idempotency to avoid duplicate interchange, group, or transaction numbers.
Trend exceptions by root cause
Measure errors by partner, document, map, field, source system, and recurrence—not just total failed messages.
The Cleo difference
Fix the transaction—and the business process around it
Basic EDI monitoring tells you a document failed. Cleo Integration Cloud connects EDI, API, MFT, and application workflows so teams can trace an exception across the partner, document, map, system, and order lifecycle.
Intelligent Exception Management helps detect failed, delayed, abnormal, or at-risk transactions, classify related errors, surface likely root causes, and provide guided resolution paths. Cleo Visibility & Business Insights adds live order views, drilldowns, scorecards, anomaly detection, and role-based context. Teams that want operational help without losing control can use Managed EDI in self-service, managed, or blended models.
For errors that can become retail deductions—late acknowledgments, incomplete ASNs, missed invoice windows, or labeling failures—Cleo Chargeback Prevention is designed to surface at-risk orders while there is still time to act.
Watch the video
See Cleo in action
Prefer a visual walkthrough? Watch this video, then explore how Cleo connects integration visibility, exception context, and operational action.
reduction in SLA errors
Verst Logistics reduced its error rate from 4% to 0.24% after modernizing EDI and API integration with Cleo.
Our error rate has dropped from 3% to 4% to 0.24%.
Macy Bergoon · VP of IT, Verst Logistics
faster issue response and resolution
Mohawk Global brought more EDI integration in-house, shortened resolution time by at least 60%, and reported $5,000 in monthly savings.
Direct access to the map and communication means less time troubleshooting EDI issues.
Terri Sandine · Manager of Application Development, Mohawk Global
See errors in business context—before partners call
Explore how Cleo can connect acknowledgment monitoring, partner transactions, source systems, exception resolution, and chargeback risk in one operational view.
Frequently asked questions
EDI error code FAQs
What does an EDI 997 rejection mean?
A rejected 997 means the receiving system found a functional-group or transaction-set syntax problem. Read AK9 for group status, AK5 for transaction status, AK3 for the segment, and AK4 for the element. A 997 usually does not prove business acceptance.
What is the difference between a TA1 and a 997?
A TA1 validates the ISA/IEA interchange envelope. A 997 reports status for the functional group and its transaction sets. Fix a TA1 problem at the envelope or partner-profile level; use the 997 detail to trace transaction syntax.
What is the difference between a 997 and a 999?
Both acknowledge X12 content, but the 999 is designed to communicate more implementation-syntax detail using IK and context segments. The acknowledgment required and the validation performed depend on the standard version and trading-partner agreement.
Does an accepted 997 mean the purchase order or invoice was accepted?
No. It generally confirms syntax-level acceptance, not that the receiving application accepted the business terms. Monitor the relevant business acknowledgment or application response as well.
Should I reuse or change the control number when resending rejected EDI?
Follow the trading partner’s replay policy. Some partners expect a corrected document with a new control number; others use specific replacement procedures. Never resend an entire partially accepted group without confirming which transactions were accepted.
How can Cleo help troubleshoot EDI errors?
Cleo connects EDI, API, MFT, and application workflows with transaction visibility, exception classification, business context, guided resolution, and flexible managed services. That helps teams move from a code in a log to the affected partner, document, order, and likely root cause.