X12 997 Acknowledgement Detailed Guide

Document created by thanh_n88 Employee on Jun 13, 2018Last modified by thanh_n88 Employee on Aug 2, 2018
Version 32Show Document
  • View in full screen mode
Your incoming X12 documents are being validated against the defined X12 document type profiles in your trading partner component, in the "Document Types" tab, not the profiles used in the maps of your processes

Now that X12 documents are validated, knowing the X12 997 Acknowledgment structure and error codes in Boomi's terms will be helpful. We'll go over what the segments in the 997 mean first and then dive into the error codes and what they mean specifically. 


Reference Guide Articles


Standard 997 Structure

Here's are example 997's, for the sake of readability, spaces are added before and after the delimiter, otherwise normal X12 documents do not usually have extra spaces. Their interchange header and interchange trailer are the same:

ISA * 00 * 0000000000 * 00 * 0000000000 * 12 * 8038025150 * 08 * 4532345856 * 180612 * 1154 * U * 00401 * 000000008 * 0 * P * >~
GS * FA * 8038025150 * 4532345856 * 20180612 * 1154 * 15 * X * 004010~


IEA * 1 * 000000014~

997 A, with one transaction set997 B, with multiple transaction set997 C, with multiple functional groups
ST * 997 * 0001~
AK1 * PO * 2~
AK2 * 850 * 103465910~
AK3 * REF * 3 * * 8~
AK4 * 1 * * 7 * BM~
AK3 * REF * 4 * * 8~
AK4 * 1 * * 7 * DP~
AK5 * R * 4 * 5~
AK9 * R * 1 * 1 * 0~
SE * 10 * 0001~
GE * 1 * 8~
ST * 997 * 0001~
AK1 * PO * 2~
AK2 * 850 * 103465910~
AK5 * A~
AK2 * 850 * 103465911~
AK5 * R * 4~
AK9 * R * 2 * 2 * 0 * 5~
SE * 8 * 0001~
GE * 1 * 13~
ST * 997 * 0001~
AK1 * PO * 2~
AK2 * 850 * 103465910~
AK5 * A~
AK2 * 850 * 103465911~
AK5 * R * 4~
AK9 * R * 2 * 2 * 0 * 5~
SE * 8 * 0001~
ST * 997 * 0002~
AK1 * SH * 3~
AK9 * A * 0 * 0 * 0~
SE * 4 * 0002~
GE * 2 * 14~

Each transaction set should have its own AK2 segment and each functional group has its own ST/SE. There is only one GE since it is for the 997 and not the original X12 document


The 997 reports each error encountered while processing the received document. If your 997 does not include AK2-AK5, see reference guide above to change your trading partner's profile settings. It is wrapped by an envelope like any other X12 document. We're going to assume the envelope is fine and only work with the AK segments for the rest of this article. The segments of the 997 mean the following:


Segment IDElementWhat is it?
AK1Functional group response header, contains information about the functional group
AK101Functional group ID (GS01) of the functional group
AK102Group control number (GS06/GE02) of functional group
AK2Transaction set response header, contains information about the transaction set. There will be an AK2 loop for each transaction set which includes the AK3, AK4 and AK5 segments, if they are applicable
AK201Transaction set ID (ST01) of the transaction set
AK202Transaction set control number (ST02/SE02) of the transaction set
AK3Data segment note, tells you the error and where it is. Each segment that causes an error gets an AK3 segment in the 997
AK301Segment ID causing the error
AK302Segment count (location) of the segment causing the error. The count starts at the ST segment, so the ST has a location of "1"
AK303Values of the LS and LE segments that surround the bounded loop causing the error, if applicable
AK304Error code of the AK3 segment, see AK304 list
AK4Data element note, generates if the AK304 error code is an "8" which means "Segment has data element errors" to give more information about the element in the erring segment
AK401Data element count (location) in the segment. If AK301 identifies the erring segment as REF, and AK401 is 1, then the data element causing the issue is REF01; if AK401 is 3, then REF03
AK402If applicable, the simple X12 data element reference number of the erring segment. For example, ST01's data element number is 143
AK403Error code of the AK4 segment, see AK403 list
AK404Value of the identified data element in error, if applicable 
AK5Transaction set response trailer, tells whether the transaction set is accept or rejected and why
AK501Code of the AK5 segment for acceptance or rejection, see AK501 list
AK502 - AK506If applicable, error code of the AK5 segment, see AK502 - AK506 list
AK9Functional group response trailer, tells whether the functional group is accept or rejected and why
AK901Code of the AK9 segment for acceptance or rejection, see AK901 list
AK902Number of transaction sets in the functional group (GE01)
AK903Number of transaction sets received
AK904Number of transaction sets accepted
AK905 - AK909If applicable, error code of the AK9 segment, see AK905 - AK909 list


Note: Functional groups are made up of one or more transaction sets (denoted by GS/GE) and transaction sets are the individual X12 documents, like an 850 (denoted by ST/SE)


Example of How to Read a Part of the 997

Now let's put it all together, we'll use this:

AK3 * REF * 3 * * 8~
AK4 * 1 * * 7 * BM~

We'll start with AK3:

  1. AK301 is "REF" and AK302 is "3", that means line 3 of your X12 document (not including the ISA and GS remember?) there is a segment REF and it has an issue
  2. AK304 is "8", that means an AK4 was generated and there's an issue with an element in the REF segment
  3. AK401 is "1", in segment REF, position 1 (i.e. REF01) there's a reported error
  4. AK403 says the error code is "7", which is an "invalid code value" and the value of REF01 is "BM", so "BM" is an invalid code value
  5. Go to the appropriate section in the error codes below and we see what that actually means. Translated for the platform, it means the qualifier is not defined in the profile (in the profile used in the document types of the trading partner)
  6. To fix, either add the qualifier into the profile or make sure your partner is using the correct qualifier 


Error Codes

Each set of error code will have their explanation and what it actually looks like in the platform, possible causes and options for solutions. 


AK304 Codes


CodeErrorResulting AK3
1Unrecognized segment IDAK3 * FGH * 2 * * 1~

Cause: A segment present in the document is not defined in the profile e.g. "FGH" is segment ID that does not exist in the profilee

Solution: Remove the segment if it is incorrect or add it to the profile

3Mandatory segment missingAK3 * BEG * 1 *  * 3~

Cause: A mandatory segment is missing from X12 document e.g. segment BEG is usually mandatory in 850 documents and your document is missing it

Solution: Add the mandatory segment in the document or make it not mandatory in the profile via the EDI Segment Details window (the "Mandatory" checkbox)

8Segment has data element errors

AK3 * BEG * 2 * * 8~

Cause: The segment has an error because of an element in the segment e.g. BEG has an error with its element

Solution: Resolve your element errors according to the AK4 segment details


AK403 Codes

AK4 only exists if he AK304 is an "8", referring to an error in the element of the segment.


CodeErrorX12 DocumentResulting AK4
1Mandatory data element missing

BEG * 00 * SA * * * 20020624~

AK3 * BEG * 2 * * 8~

AK4 * 3 * * 1~

Cause: An element in the segment is mandatory but is missing from the X12 document e.g. BEG03 is missing and it is a mandatory element

Solution: Add the mandatory element or make it not mandatory in the profile via the EDI Element Details window (the "Mandatory" checkbox)

4Data element is too short

REF * * 1105658 * ABC GLASS~

when the minimum length of the element is 2 in the profile

AK3 * REF * 3 * * 8~

AK4 * 1 * * 4 * B~

Cause: An element has less characters than the specified minimum length in the profile e.g. REF01 has field length validation of a minimum of 2, but here it is only one, "B"

Solution: Make sure your element meets the minimum length; change your minimum length or turn off the "Field Length Validation" option in the profile under the Field Size Options in the EDI Element Details window

5Data element is too long

REF * DFAAAAA * 1105658 * ABC GLASS~

when the maximum length of the element is 4 in the profile

AK3 * REF * 5 * * 8~

AK4* 1 * * 5 * DFAAAAA~

Cause: An element has more characters than the specified maximum length in the profile e.g. REF01 has field length validation of a maximum of 4, but here it is over, "DFAAAAA"

Solution: Make sure your element meets the maximum length; change your maximum length or turn off the "Field Length Validation" option in the profile under the Field Size Options in the EDI Element Details window

7Invalid code value

REF * NJ* 1105658 * ABC GLASS~

when "NJ" is not a qualifier defined for a segment's element in the profile

AK3 * REF * 12 * * 8~
AK4 * 1 * * 7 * NJ~

Cause: There's no qualifier defined for that element in the profile e.g. there's no qualifier "NJ" defined for the segment REF01

Solution: Add the missing qualifier to the X12 document profile or double check the correct segment element is being sent

Note: If no qualifiers are defined in the profile, this error code will not be flagged for the above cause


AK501/AK901 Codes


Error CodeMeaning
EAccepted with Errors
PPartially accepted, at least one transaction set was rejected


AK502 - AK506 Codes

If there are multiple errors, each segment in AK502 to AK506 will populate accordingly


CodeErrorX12 DocumentResulting AK4
2Transaction set trailer missingLack of SE segmentAK5 * R * 2~

Cause: The SE segment is missing

Solution: Add a valid SE segment

3Transaction set control number in header and trailer do not match

ST * 850 * 103465911~

SE * 103 * 103465910~

AK5 * R * 3~

Cause: ST02 is different from the SE02 or vice versa e.g. 103465911 is not 103465910; SE02 is empty

Solution: Make sure they are the same, valid value

4Number of included segments does not match actual count

SE * 103 * 103465910~ but you have only 99 lines since you accidentally included 4 for the ISA, GS, GE, and IEA envelope segments

AK5 * R * 4~

Cause: The SE01 element has a different number than the total number of lines. Total number of lines start from ST being line "1" and counts until the SE segment. In this case the SE01 could have been 103, but you have more or less or another error is causing it because that segment is not being read properly due to some sort of error

Solution: Change SE01 to the correct number of segments

5One or more segments in error

Cause: Whenever your non-ST/SE/GS/GE segments have errors, you will get this error code

Solution: Resolve your segment errors

7Missing or invalid transaction set control number

ST * 850 *~

AK5 * R * 3 * 7~

Cause: ST02 is empty

Solution: Give ST02 a valid value


AK905 - AK909 Codes

If there are multiple errors, each segment in AK905 to AK909 will populate accordingly


CodeErrorX12 DocumentResulting AK4
3Functional group trailer missing

Lack of GE segment

AK9 * R * 1 * 1 * 0 * 3~

Cause: Missing GE segment

Solution: Add a valid GE segment

4Group control number in the functional group header and trailer do not agree

GS * PO * 4532345856 * 8038025150 * 20020624 * 1158 * ABC * X * 004010~

GE * 1 * ABD~

AK9 * R * 1 * 1 * 0 * 4~

Cause: GS06 and GE02 are not the same value or one of them is empty

Solution: Give GS06 and/or GE02 the same, valid value

5Number of included transaction sets does not match actual count

GE * * 13512~

but there are more or less than five transaction sets i.e. more or less than five 850's

AK9 * R * 1 * 1 * 0 * 5~

Cause: GE01 does not agree with the actual number of transaction sets in a functional group

Solution: Verify the number of transaction sets and update GE01 accordingly. 


Special Thanks

To Medha for helping with all of the error definitions and testing

3 people found this helpful