SOAPless
Sign Up
Back to Blog
soap-errorsnetworkingtroubleshooting

SOAP Connection Timeout and Connection Refused: Troubleshooting Guide

SOAPless Team6 min read

Connection timeouts and "connection refused" errors are among the most common issues when integrating with SOAP services. Unlike SOAP faults (which at least tell you the server received your request), connection-level failures mean your request never reached the service — or the service isn't responding at all. These errors are networking problems, not SOAP problems, but they disproportionately affect SOAP integrations because many SOAP services run on older infrastructure with stricter network requirements.

This guide walks through every realistic cause and gives you concrete diagnostic steps.

Timeout vs. Connection Refused: What's the Difference?

These are two distinct failure modes:

  • Connection timeout means your client sent a TCP SYN packet but never received a SYN-ACK. The server is either unreachable, a firewall is silently dropping packets, or the server is too overloaded to accept new connections. Your client waits until its timeout threshold expires, then gives up.

  • Connection refused (TCP RST) means the server is reachable at the network level, but nothing is listening on the target port. The OS responds immediately with a reset packet. This is usually faster than a timeout — you get the error within milliseconds.

# Timeout — hangs, then fails
Error: connect ETIMEDOUT 10.0.1.50:8443

# Connection refused — fails immediately
Error: connect ECONNREFUSED 10.0.1.50:8443

Cause 1: Firewall Rules Blocking Traffic

This is the most common cause of connection timeouts, especially in enterprise environments. SOAP services frequently run behind corporate firewalls that whitelist specific IP addresses or CIDR ranges.

Diagnosis:

# Check if the port is reachable
nc -zv api.example.com 443 -w 5

# Trace the route to see where packets stop
traceroute -p 443 api.example.com

# Check with telnet
telnet api.example.com 443

If nc hangs and eventually times out, a firewall is likely dropping your packets. If it connects instantly, the network path is clear.

Fix: Contact the service provider and ask them to whitelist your server's public IP address. If you're running on a cloud provider (AWS, GCP, Azure), make sure your outbound security group or network ACL rules allow traffic on the target port. Also check your own server's outbound firewall — iptables or ufw rules can silently block outgoing connections.

Cause 2: DNS Resolution Failures

If the hostname doesn't resolve to an IP address, the connection attempt never starts. This manifests differently depending on the client — sometimes as a timeout, sometimes as a specific DNS error.

# Verify DNS resolution
dig api.example.com
nslookup api.example.com

# Check if the resolved IP is correct
host api.example.com

Common DNS issues:

  • The service uses an internal DNS name that's only resolvable within their network
  • DNS records have been updated but your server has a stale cache
  • Your server's /etc/resolv.conf points to a DNS server that can't resolve the hostname

Fix: If the hostname resolves to an internal IP (10.x.x.x, 172.16-31.x.x, 192.168.x.x), you need VPN access or a direct network connection. For stale DNS, flush your cache with sudo systemd-resolve --flush-caches (Linux) or sudo dscacheutil -flushcache (macOS).

Cause 3: SSL/TLS Handshake Failures

SOAP services often use HTTPS with specific TLS requirements. If the TLS handshake fails, the symptom may look like a connection timeout or a vague "connection reset" error.

# Test SSL connectivity and see the full handshake
openssl s_client -connect api.example.com:443 -servername api.example.com

# Check which TLS versions the server supports
nmap --script ssl-enum-ciphers -p 443 api.example.com

Common TLS issues:

  • The server requires TLS 1.2+ but your client is attempting TLS 1.0 or 1.1
  • The server's certificate is expired, self-signed, or issued for a different hostname
  • The server requires client certificate authentication (mutual TLS)
  • Cipher suite mismatch — the server only accepts ciphers your client doesn't support

Fix for Node.js:

import https from "https";
import { Agent } from "https";

const agent = new Agent({
  // Accept self-signed certs (development only!)
  rejectUnauthorized: false,
  // Force minimum TLS version
  minVersion: "TLSv1.2",
  // Provide client certificate if required
  cert: fs.readFileSync("client-cert.pem"),
  key: fs.readFileSync("client-key.pem"),
});

Important: Never use rejectUnauthorized: false in production. Instead, add the server's CA certificate to your trust store.

Cause 4: Incorrect Endpoint URL

SOAP services have specific endpoint URLs that may differ from the WSDL URL. A common mistake is sending SOAP requests to the WSDL URL instead of the service endpoint.

<!-- The WSDL specifies the actual endpoint in the service section -->
<wsdl:service name="UserService">
  <wsdl:port name="UserServicePort" binding="tns:UserServiceBinding">
    <soap:address location="https://api.example.com/services/UserService"/>
  </wsdl:port>
</wsdl:service>

Fix: Check the <soap:address location="..."/> element in the WSDL. That URL is where your SOAP requests should be sent — not the URL you used to fetch the WSDL.

Cause 5: Proxy Configuration

In corporate environments, outbound HTTP traffic often goes through a proxy server. If your SOAP client isn't configured to use the proxy, connections to external services will timeout.

# Check if proxy environment variables are set
echo $HTTP_PROXY $HTTPS_PROXY $NO_PROXY

Fix for Node.js:

import { HttpsProxyAgent } from "https-proxy-agent";

const proxyAgent = new HttpsProxyAgent("http://corporate-proxy.example.com:8080");

const response = await fetch("https://api.example.com/Service", {
  method: "POST",
  agent: proxyAgent,
  headers: { "Content-Type": "text/xml" },
  body: soapEnvelope,
});

Cause 6: Keep-Alive and Connection Pooling

Some SOAP servers close idle connections aggressively. If your HTTP client reuses a connection that the server has already closed, you'll get a "connection reset" error on the next request.

Fix: Configure your HTTP client to handle stale connections:

const agent = new https.Agent({
  keepAlive: true,
  keepAliveMsecs: 10000,
  maxSockets: 10,
  // Timeout idle sockets before the server does
  timeout: 30000,
});

Diagnostic Checklist

Run through these steps in order when you hit a connection failure:

  1. Verify DNS resolution — Can you resolve the hostname?
  2. Test raw TCP connectivity — Can you reach the port with nc or telnet?
  3. Test TLS handshake — Does openssl s_client succeed?
  4. Send a minimal HTTP request — Does curl -v to the endpoint return anything?
  5. Check endpoint URL — Are you targeting the service endpoint, not the WSDL URL?
  6. Check proxy settings — Is a proxy required for outbound access?
  7. Check firewall rules — Both your outbound rules and the provider's inbound rules.
# One-liner diagnostic
curl -v --connect-timeout 10 "https://api.example.com/services/UserService?wsdl" 2>&1

The -v flag in curl shows the full connection attempt, including DNS resolution, TCP handshake, and TLS negotiation. This single command often reveals exactly where the failure occurs.

When Connection Issues Become Ongoing Pain

If you're dealing with intermittent connection issues to a SOAP service — timeouts during peak hours, TLS version mismatches after server updates, or proxy configuration headaches across different deployment environments — a proxy layer can absorb this complexity. SOAPless maintains persistent connections to your SOAP services, handles TLS negotiation and retry logic, and exposes a standard REST endpoint that your application connects to. Your code talks to a reliable, modern HTTPS endpoint instead of wrestling with legacy network configurations.

Regardless of your approach, the diagnostic steps above will help you identify the root cause of any SOAP connectivity issue.

Back to Blog