When Your AS2 Connection Fails, Start Here

Your AS2 message didn't go through. The error log shows something cryptic. Your trading partner says they see nothing on their end. You're staring at a stack trace that could mean five different things.

This guide covers every common AS2 connection failure, organized by error type. For each one: what causes it, how to diagnose it, and the exact fix. Bookmark this. You'll be back.

TLS Handshake Failures

TLS failures kill the connection before any AS2 protocol exchange happens. Your system tries to establish an encrypted HTTPS connection to your partner's endpoint, and the handshake dies. No message is sent. No MDN is generated. The AS2 layer never executes.

"SSL handshake failure" or "TLS handshake failed"

What's happening: Your system and your partner's system can't agree on how to encrypt the connection. This is the most common TLS error in AS2, and it has several root causes.

Diagnose it:

# Check what TLS versions the partner supports
openssl s_client -connect partner.example.com:443 -tls1_2
openssl s_client -connect partner.example.com:443 -tls1_3

# See the full handshake details
openssl s_client -connect partner.example.com:443 -debug

If -tls1_2 fails but -tls1_3 works (or vice versa), you have a TLS version mismatch. Configure your AS2 system to use the version your partner supports.

"cipher suite mismatch" or "no shared cipher"

What's happening: Both sides support the same TLS version, but they don't share any cipher suites. Your system offers a list of ciphers. Your partner's system offers a different list. No overlap means no connection.

Diagnose it:

# List ciphers the partner accepts
nmap --script ssl-enum-ciphers -p 443 partner.example.com

# Or use openssl to test specific ciphers
openssl s_client -connect partner.example.com:443 -cipher ECDHE-RSA-AES256-GCM-SHA384

Fix: Compare the cipher lists. Add the partner's supported ciphers to your TLS configuration. For TLS 1.2, safe choices include ECDHE-RSA-AES256-GCM-SHA384 and ECDHE-RSA-AES128-GCM-SHA256. For TLS 1.3, cipher suites are fixed by the protocol, so a version match is usually enough.

If your partner only supports weak ciphers (RC4, DES, export-grade), that's a security conversation. Don't weaken your configuration to accommodate them.

"certificate verify failed" or "unable to verify server certificate"

What's happening: Your system doesn't trust your partner's TLS certificate. This is different from AS2-level certificate issues. This is the HTTPS transport layer rejecting the server's identity.

Common causes:

Partner's TLS certificate is self-signed and your system only trusts CA-signed certificates
Missing intermediate CA certificate in the partner's TLS chain
Your system's CA trust store is outdated (missing newer root CAs)
Certificate hostname doesn't match the URL you're connecting to

Fix:

# Download and inspect the partner's certificate chain
openssl s_client -connect partner.example.com:443 -showcerts

# Verify the chain against your trust store
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt partner_tls_cert.pem

If the chain is incomplete, ask your partner to configure their web server to serve the full chain (including intermediates). If their certificate is self-signed, you'll need to add it to your system's trust store explicitly.

"certificate has expired" (TLS level)

What's happening: Your partner's TLS certificate (the one on their web server, not their AS2 signing certificate) has expired. Your system refuses to connect.

Diagnose:

echo | openssl s_client -connect partner.example.com:443 2>/dev/null | openssl x509 -noout -dates

Fix: This is your partner's problem. Notify them. There's nothing you can configure on your end to work around an expired server certificate safely. Some teams disable certificate verification as a "temporary fix." Don't. That defeats the purpose of TLS entirely and opens you to man-in-the-middle attacks.

HTTP Errors

You got past the TLS handshake. The HTTP connection is established. But the AS2 message delivery fails with an HTTP status code. Here's what each one means in an AS2 context.

401 Unauthorized

What's happening: Your partner's AS2 endpoint requires HTTP Basic Authentication or client certificate authentication, and you're not providing it.

Fix: Ask your partner if their endpoint requires HTTP-level authentication (separate from AS2 message signing). If yes, get the credentials and configure them in your AS2 software's partnership settings. In OpenAS2, this goes in the partnership's HTTP headers. In most commercial products, there's a username/password field in the partner configuration.

Note: HTTP authentication is separate from AS2 message encryption and signing. Some partners use both. Some use only AS2-level security. Confirm what's required.

403 Forbidden

What's happening: Your partner's server recognizes your request but refuses to serve it. Common causes:

IP whitelisting: your server's IP isn't on their allow list
WAF (Web Application Firewall) blocking the request based on payload inspection
Client certificate required but not provided
Your AS2 message is being flagged as suspicious by their security layer

Fix: Provide your partner with your server's public IP address (or IP range if you use multiple egress IPs). Ask them to whitelist it. If they use a WAF, they may need to create an exception rule for AS2 traffic, which has unusual Content-Type headers and binary payloads that security tools sometimes flag.

404 Not Found

What's happening: You're hitting the wrong URL. The AS2 endpoint path is incorrect.

Fix: Verify the exact AS2 endpoint URL with your partner. Common path issues:

/as2 vs /AS2 vs /as2/receive vs /as2/HttpReceiver. Paths are typically case-sensitive.
Trailing slash matters on some servers: /as2 vs /as2/
Partner migrated to a new URL and the old one was decommissioned

# Quick check: does the URL respond at all?
curl -v -X POST https://partner.example.com/as2

A 404 at least confirms TLS and network connectivity are working. You're close.

500 Internal Server Error

What's happening: Your partner's AS2 server crashed while processing your message. This is their bug, not yours. But you can help them diagnose it.

Common triggers:

Your message is encrypted with an algorithm they don't support
Your signing certificate uses a key size their system can't handle (rare, but some legacy systems choke on 4096-bit keys)
The payload exceeds their system's memory limits
Their AS2 software has a bug triggered by a specific header combination

Fix: Send them the exact timestamp of your attempt and your AS2 ID. Ask them to check their server logs for the corresponding error. While you wait, try sending a minimal test payload (small text file, basic encryption settings) to isolate whether the issue is payload-specific.

502 Bad Gateway

What's happening: Your partner's load balancer or reverse proxy is up, but the backend AS2 server behind it is down or unreachable.

Fix: This is their infrastructure issue. Notify them. The reverse proxy received your request but couldn't forward it to the actual AS2 application. They need to check if their AS2 service is running.

503 Service Unavailable

What's happening: Your partner's server is temporarily overloaded or undergoing maintenance.

Fix: Retry after a few minutes. If the error persists for more than 30 minutes, contact your partner. Most AS2 software has built-in retry logic. Configure it with exponential backoff: first retry at 5 minutes, second at 15 minutes, third at 1 hour. Don't hammer a struggling server with rapid retries.

Connection and Network Errors

"Connection refused"

What's happening: Your system reached the partner's IP address, but nothing is listening on the target port. The operating system actively rejected the connection.

Causes:

Partner's AS2 server is stopped
Wrong port in the endpoint URL
Partner's firewall is sending RST packets instead of silently dropping

Diagnose:

# Is the port open?
nc -zv partner.example.com 443

# Check from different network paths if possible
curl -v --connect-timeout 5 https://partner.example.com/as2

Fix: Confirm the port with your partner. If the port shows as closed, they need to verify their AS2 service is running and their firewall allows inbound connections on that port.

"Connection timed out"

What's happening: Your system sent packets but received no response. The packets are being silently dropped, either by a firewall, a misconfigured route, or a down server.

This is different from "connection refused": refused means something actively said "no." Timeout means nothing responded at all. Timeouts take longer to detect (your system waits for its timeout period, usually 30 to 60 seconds) and are harder to diagnose.

Diagnose:

# Trace the network path
traceroute partner.example.com

# Check if the host is reachable at all
ping partner.example.com

# Test specific port with timeout
nc -zv -w 5 partner.example.com 443

Common causes and fixes:

Firewall blocking: Your egress firewall or their ingress firewall is dropping the traffic. Provide your IP to your partner for whitelisting. Check your own outbound rules.
Wrong IP/DNS: The hostname resolves to the wrong IP. Run nslookup partner.example.com and verify the IP with your partner.
VPN required: Some partners require a site-to-site VPN for AS2 traffic. The public internet path won't work.
NAT issues: If you're behind NAT, your outbound packets may be reaching the partner with an unexpected source IP that's not whitelisted.

"DNS resolution failed" or "Could not resolve host"

What's happening: Your system can't translate the partner's hostname into an IP address.

Diagnose:

nslookup partner.example.com
dig partner.example.com

Causes:

Typo in the hostname. Check the URL letter by letter.
Partner's DNS record was removed or changed. Verify the current hostname with them.
Your DNS resolver is down or misconfigured. Try a public resolver: nslookup partner.example.com 8.8.8.8
If the partner uses a private DNS zone (internal network), you may need VPN access or a DNS forwarder configured.

AS2 Protocol Errors

These errors occur after the TLS handshake succeeds and the HTTP connection is established. The AS2 message was delivered to the partner's system, but the AS2 protocol processing failed.

"Message Disposition: failed" in MDN

What's happening: Your partner's system received the AS2 message but couldn't process it. The MDN comes back with a failure disposition instead of "processed."

Check the MDN body for specifics:

"decryption-failed": Your partner can't decrypt the message. You're encrypting with a certificate that doesn't match their private key. Either you have an outdated certificate for them, or they rotated their key pair and didn't send you the new public certificate.
"authentication-failed": Your signature couldn't be verified. Your partner has an old or wrong public certificate for you. Send them your current certificate.
"insufficient-message-security": Your message doesn't meet their security requirements. Common cause: you're sending unsigned messages and they require signing, or you're using SHA-1 and they require SHA-256.

"No MDN received"

What's happening: You sent the message. No MDN came back. This doesn't necessarily mean the message failed.

For synchronous MDN: The partner's system didn't include an MDN in the HTTP response. Their AS2 software may be misconfigured for this partnership, or it crashed during processing (check for HTTP 500).

For asynchronous MDN: The partner sent the MDN to your receipt URL, but it didn't arrive. Diagnose:

Is your MDN receipt URL correct in the AS2 message headers? Check the Receipt-Delivery-Option header.
Is that URL reachable from your partner's network? Ask them to curl it.
Is your firewall blocking their inbound MDN POST request?
Did their system even attempt to send the MDN? Ask them to check their outbound logs.

"AS2-From/AS2-To mismatch"

What's happening: The AS2-From and AS2-To headers in your message don't match what your partner has configured. These identifiers are case-sensitive string matches.

Fix: Get the exact AS2 IDs from your partner. Copy and paste them. Check for leading or trailing whitespace. Some AS2 GUIs trim whitespace on input; others don't. A space you can't see will break the match.

Payload and Content Errors

"Payload too large" or HTTP 413

What's happening: Your AS2 message exceeds the maximum size your partner's server accepts. AS2 messages include the encrypted and signed payload plus MIME wrappers, so the transmitted size is significantly larger than the raw file.

Common limits:

Default Nginx: 1MB (client_max_body_size)
Default Apache: 2GB (usually not the bottleneck)
Default IIS: 30MB (maxAllowedContentLength)
Many AS2 implementations: 50 to 100MB configurable

Fix: Ask your partner what their maximum message size is. If your payload is genuinely large, you have options: split the EDI interchange into smaller messages, compress the payload before AS2 wrapping (AS2 supports built-in compression via Content-Transfer-Encoding: zlib), or ask your partner to increase their limit.

"Content-Type mismatch"

What's happening: The Content-Type header doesn't match what the partner's system expects. You're sending application/edi-x12 but their system is configured to accept only application/edifact, or vice versa.

Fix: Confirm the expected Content-Type with your partner. Standard values:

X12 EDI: application/edi-x12
EDIFACT: application/edifact
XML: application/xml
Generic fallback: application/edi-consent (accepted by most systems)

A Systematic Debugging Approach

When an AS2 connection fails and you're not sure where to start, work through these layers in order. Each layer depends on the one below it. If a lower layer is broken, nothing above it works.

DNS: Can you resolve the hostname? nslookup partner.example.com
Network: Can you reach the IP on the correct port? nc -zv partner.example.com 443
TLS: Does the handshake complete? openssl s_client -connect partner.example.com:443
HTTP: Does the server respond to requests? curl -v -X POST https://partner.example.com/as2
AS2 identity: Are your AS2-From and AS2-To headers correct?
Certificates: Is the right certificate configured for encryption and signing?
Encryption/Signing: Do both sides agree on algorithms?
MDN: Is the MDN type (sync/async) and signing algorithm agreed upon?

If step 1 fails, don't bother testing step 5. Fix the lowest broken layer first, then work upward.

Stop Debugging Blind

The hardest part of AS2 troubleshooting isn't fixing the problem. It's finding which layer is broken. A TLS cipher mismatch, a wrong AS2 ID, and an expired certificate all produce similarly vague error messages in most AS2 software. You end up guessing, changing one setting at a time, sending another test, waiting for your partner to check their logs, and repeating.

AS2 Certify eliminates the guessing. It runs an 8-step diagnostic against your AS2 endpoint, testing every layer described in this guide: DNS resolution, network connectivity, TLS handshake (including cipher and version negotiation), HTTP response handling, AS2 identity matching, certificate validation, encryption and signing verification, and MDN exchange. Each step produces a clear pass or fail with specific details about what broke.

You get a graded report (A through F) in minutes instead of spending days on back-and-forth emails with your trading partner. When something fails, the report tells you exactly which layer broke and why, so you can fix it in one shot instead of playing whack-a-mole with configuration changes.

Quick Reference: Error to Fix

Keep this table handy for fast lookups:

TLS handshake failed → Check TLS version and cipher suite compatibility
Certificate verify failed → Missing intermediate cert or expired TLS certificate
Connection refused → Wrong port, service not running, or firewall RST
Connection timed out → Firewall dropping packets, wrong IP, VPN required
DNS resolution failed → Typo in hostname, DNS server issue, private DNS zone
401 Unauthorized → HTTP authentication required, credentials missing
403 Forbidden → IP not whitelisted, WAF blocking, client cert required
404 Not Found → Wrong AS2 endpoint URL path
500 Internal Server Error → Partner's server crashed, check with them
502 Bad Gateway → Partner's backend AS2 service is down
503 Service Unavailable → Partner's server overloaded, retry later
413 Payload Too Large → Message exceeds partner's size limit
Decryption failed (MDN) → Wrong encryption certificate, partner rotated keys
Authentication failed (MDN) → Partner has wrong signing certificate for you
No MDN received → Async MDN URL unreachable, or sync MDN not sent
AS2-From/To mismatch → Case-sensitive ID error, extra whitespace