AS2 Troubleshooting

AS2 is a protocol to transmit signed and encrypted business data payloads over HTTP. AS2 also has a mechanism for confirmation of both receipt and message integrity.

AS2 overview

For AS2 transmission, the sender and receiver:

Are represented with their AS2 ID
Own encryption certificates they associate with their AS2 ID (they provide their public key to the other party)
Have an endpoint to receive AS2 messages

The AS2 ID and certificate is used to secure the message by encryption and to authenticate the sender using hash-based signatures.

AS2 step-by-step

The broad steps for AS2 transmission are:

Sender encrypts and signs (including integrity check)
Transmission
Receiver decryption and verifies signature (including integrity check)
Receiver confirms receipt and integrity

Before an AS2 message can be transmitted, the two partners must exchange certificates. Each partner inputs the other’s certificate into their AS2 software.

To begin, the sender’s AS2 software encrypts and signs the X12-formatted EDI document using a Message Integrity Check (MIC). The sender then transmits the EDI document to a specified URL along with AS-To and AS-From headers that specify the AS2 IDs of the sender and receiver.

The receiver accepts the message and decrypts it. The receiver calculates the MIC and ensures that it matches the MIC in the sender’s signature. If everything matches, the recipient generates and signs a Message Disposition Notification (MDN), which is returned to the sender. The MDN includes the MIC of the original message, which the sender can use as a guarantee that the recipient is processing the same content that was sent.

The sender gets back the MDN and compares the MIC returned by the receiver to the one that was calculated before the message was sent.

Using AS2 with Orderful

To send and receive AS2 data with Orderful you will need both an Inbound and an Outbound AS2 Communication Channel.

Outbound AS2: Your Outbound AS2 will be how you send your AS2 messages to Orderful, and Orderful will then pass your data on to your Trading Partner.

Inbound AS2: Your Inbound AS2 will be how Orderful will send you AS2 messages that you then ingest into your backend system.

In order to use AS2 with Orderful, you should start by creating an Inbound AS2 channel. Orderful automatically creates an Outbound AS2 Communication Channel when you create an Inbound one.

Instructions for creating an Inbound AS2 Communication Channel can be found here: https://docs.orderful.com/docs/inbound-as2

📘
Orderful only supports synchronous, encrypted AS2 transmission with no compression using HTTPS or HTTP. Asynchronous transmission, compressed data and unencrypted data are not supported.

AS2 and HTTP Errors

Errors can arise at any of the major points in AS2 transmission, either on the way to or from Orderful. Errors can occur either as a part of the HTTP transfer, resulting in HTTP errors, or once the message reaches the AS2 server, resulting in AS2 errors. In general, AS2 errors fall into one these categories:

Issues with the sender and/or receiver AS2 IDs.
Misconfigured encryption: decryption failure.
Misconfigured encryption: integrity check failure.
Processing errors within the AS2 server: Transactions can't be created.

In some cases, you will have to follow different troubleshooting steps depending on whether the error is in the Outbound or Inbound Communication Channels.

Inbound Errors

Inbound AS2 errors occur when Orderful is sending AS2 messages to you. You can see the errors within your software, however you can also troubleshoot errors using the audit trail for your Transaction. To see the audit trail, go to your Transactions page and click on a Transaction, then click on the checklist icon in the top right. This will bring up the audit trail modal:

Inbound HTTP Error: 400

Audit Trail: 400 Bad Request

Cause: Your server thinks the incoming AS2 message from Orderful is malformed in some way.

Solution: Check your backend server logs for more information.

Inbound HTTP Error: 401

Audit Trail: 401 Unauthorized

Cause: Your server is requesting authentication for the incoming AS2 message.

Solution: Orderful does not support additional authentication for AS2. Be sure that your server is not requesting additional authentication such as Basic Auth.

Inbound HTTP Error: 403

Audit Trail: 403 Forbidden

Cause: Your server does not think that Orderful has permission to send the incoming AS2 message.

Solution: Orderful does not support additional authentication for AS2. Be sure that your server is not requesting additional authentication such as Basic Auth.

Inbound HTTP Error 404

Audit Trail: 404 Not Found

Cause: The incoming AS2 message is being sent to a URL that cannot be found.

Solution: Make sure that you have configured the correct AS2 URL in your Incoming AS2 Communication Channel.

Inbound HTTP Error: 500

Audit Trail: 500 Internal Server Error

Cause: A general error has occurred within your server.

Solution: Refer to your server logs for more information.

Inbound HTTP Error: 504

Audit Trail: 504 Gateway Timeout

Cause: There was an error in a network gateway, such as your firewall.

Solution: Check your firewall settings and logs for more information.

Inbound MDN Error: Asynchronous MDN

Audit Trail: The response was empty and a synchronous MDN is required and "Delivery status" is FAILED

Cause: This will occur if you respond to a Orderful’s AS2 request with anything other than an MDN.

Solution: Configure your AS2 software to respond with synchronous MDNs. If this configuration is already present, check if there are any other possible connection issues.

Inbound MDN Error: Decryption Failed

Audit Trail: Received an MDN with errors and Delivery status FAILED

Cause: Your AS2 software is unable to decrypt the AS2 message sent from Orderful. This may be because you have uploaded the wrong certificate to Orderful, or are unable to decrypt messages that use our algorithm.

Solution: Confirm that you have uploaded the correct certificate in your Inbound Communication Channel configuration. Also confirm that your AS2 software is able to decrypt messages using the 3DES algorithm.

Inbound MDN Error: Integrity Check Failed (Signature verification)

Audit Trail: The signature is unverified. or The MDN was signed using the wrong certificate. and “Delivery status” is FAILED

Cause: Orderful was unable to match the certificate in the signature.

Solution: The Orderful Inbound AS2 Communication Channel must be updated with the correct certificate that matches the one in your AS2 software.

Inbound MDN Error: Integrity Check Failed (Message integrity)

Audit Trail: The message ID was incorrect. or The message integrity check was incorrect. and “Delivery status” is FAILED

Cause: Either the message ID is incorrect or the message contents do not match those used to generate the signature.

Solution: Ensure that your MDN response contains a message ID that matches the original AS2 message that you were sent by Orderful.

Outbound Errors

If an error occurs on your Outbound AS2 Communication Channel, your AS2 software will receive either an HTTP error response or an MDN response with further information about the error.

HTTP Error: 400

Error: 400 Bad Request

Cause: The AS2 message you sent to Orderful is malformed in some way.

Solution: Contact [email protected]

HTTP Error 404

Error: 404 Not Found

Cause: Your AS2 message was directed to an Orderful URL that could not be found.

Solution: Check that the URL configured in your AS2 software is <https://as2.orderful.com>

HTTP Error: 500

Error: 500 Internal Server Error

Cause: Orderful experienced a general server error.

Solution: Contact [email protected]

HTTP Error: 504

Error: 504 Gateway Timeout

Cause: There was an error in a network gateway, such as your firewall.

Solution: Check your firewall settings and logs for more information.

Outbound MDN Error: Asynchronous MDN

Example Disposition: The Orderful platform does not support asynchronous MDNs.

Cause: You requested an asynchronous MDN while sending your AS2 message.

Solution: Check your AS2 software and confirm that it is requesting a synchronous MDN.

Outbound MDN Error: Decryption Failed

Example Disposition: The message couldn't be decrypted and hasn't been processed by the receiver.

Cause: Orderful is unable to decrypt the AS2 message you sent. This may be because you encrypted the message using the wrong certificate, or are using an encryption algorithm Orderful is not able to decrypt.

Solution: Confirm that you have the correct Orderful certificate configured in your AS2 software. Also confirm that you are encrypting your message using one of the encryption algorithms Orderful supports: 3DES, AES128, AES192 or AES256

Outbound MDN Error: Integrity Check Failed

Example Disposition: The message was received, but could not be verified; the contents cannot be trusted to be the same contents that were sent.

Cause: Orderful could not successfully verify the signature for your AS2 message.

Solution: Confirm that you have the correct Orderful certificate configured in your AS2 software. Also confirm that you are calculating your MIC using one of the algorithms we support: SHA-1, SHA-256, SHA-384 or SHA-512

Outbound MDN Error: Missing Communication Channel

Example Disposition: No configuration using the AS2 IDs [TO ID] and [FROM ID] has been implemented.

Cause: Orderful is unable to find an Inbound AS2 Communication Channel

Solution: Confirm that you created an Inbound AS2 Communication Channel in Orderful and that your AS2 software is using the AS2-From and AS-To headers specified in your Outbound AS2 Communication Channel Details.

Outbound MDN Error: Missing Sender or Receiver

Example Disposition: Missing or empty AS2-To or AS2-From header.

Cause: Your AS2 message is missing one of the required headers.

Solution: Check that your AS2 software is configured correctly.

Outbound MDN Error: Sender Equals Receiver

Example Disposition: AS2-To is identical to AS2-From.

Cause: The value of the AS-To and the AS2-From are the same.

Solution: Check that your AS2 software is configured correctly.

Outbound MDN Error: Undergoing Maintenance

Example Disposition: Orderful is currently down for maintenance. We will be back up shortly.

Cause: The Orderful platform is down for maintenance.

Solution: Try your request again or contact [email protected]