522 Connection timed out

A 522 from the helodata gateway means the proxy couldn't reach (or finish a handshake with) the upstream IP. It's usually transient — but the X-Helodata-Error-Code distinguishes a few flavors.

upstream-timeout — backend IP didn't respond

HTTP/1.1 522
X-Helodata-Error-Code: upstream-timeout

Causes

• The selected residential/mobile/ISP IP went offline between IP selection and connection
• Target site is slow and the request exceeded the gateway's upstream timeout
• ISP IP whose carrier dropped the connection

Fix

• Just retry. Pick a new exit:

  • Gateway products: drop the session segment to get a different IP
  • ISP: switch to another IP from your batch

If you see upstream-timeout on more than 10% of requests over 5+ minutes, that's not normal — it's worth opening a ticket with a few X-Helodata-Request-Ids.

insufficient-pool — your filter is too narrow

HTTP/1.1 522
X-Helodata-Error-Code: insufficient-pool
X-Helodata-Insufficient-Pool: true

Cause — the combined geo + ASN + session filter matches fewer than 10 live IPs.

Fix — broaden the filter, in this order:

1. Drop city
2. Drop state
3. Drop asn
4. Switch country

If you genuinely need that narrow filter, contact support — we can sometimes pre-stage a larger pool for paid plans.

Target's TLS handshake timed out

HTTP/1.1 502
X-Helodata-Error-Code: upstream-tls-error

(Strictly 502, but related.)

Cause — TLS to the target site failed mid-handshake. Likely target-side: misconfigured cert, OCSP timeout, slow server.

Fix — see SSL / TLS errors.

What to do programmatically

RETRYABLE = {"upstream-timeout"}

def on_522(resp, attempt):
    code = resp.headers.get("x-helodata-error-code")
    if code == "insufficient-pool":
        # Broaden filter — don't blindly retry
        raise ConfigError("Loosen geo/ASN filter")
    if code in RETRYABLE and attempt < 5:
        time.sleep(2 ** attempt + random.random())
        return True
    return False

What 522 is not

• It's not a target 522. Cloudflare also returns 522 — that's the target site telling the proxy its origin timed out. Distinguish by the presence of X-Helodata-Error-Code:

  • Has X-Helodata-Error-Code → helodata gateway error
  • No such header, but has Server: cloudflare and a cf-ray → target's Cloudflare timing out its own backend; retry won't help much

Still seeing it

Email [e-mail] with at least one X-Helodata-Request-Id. We log the upstream IP, the target, and the timeout breakdown, and can tell you whether the issue is on our side or the target's.