# 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-Id`s.

## `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](/troubleshooting/ssl-errors.md).

## What to do programmatically

```python
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 <support@helodata.com> 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/troubleshooting/522.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.