# Check states

Every check of a proxy ends in one of four states. They are in `proxies.json`, in the CSV, in `--pick --json`, in `--diagnose`, in the Python API (`result.checks`) and in the MCP results.

| State | Meaning |
|---|---|
| `passed` | The check ran and the proxy did what was asked. |
| `failed` | The check ran, its target was fine, and the proxy did not do what was asked. |
| `unavailable` | The check could not run, or says nothing about the proxy: its target didn't answer directly either, there was no reference to compare with, or this machine ran out of sockets. |
| `skipped` | Left out on purpose: `--fast`, a filter had already ruled the proxy out, or an earlier check failed. |

Two rules follow from that:

- **A check that didn't run is never `passed`.** Before 1.30, a run without a reachable second target kept every proxy as if it had been confirmed, and a missing reference page looked like "content unchanged".
- **A check target that is down doesn't fail the proxies checked against it.** When a second request, a content request that returned a different page, or an HTTPS test fails, the tool asks the target directly: at most once every 3 seconds however many proxies fail in between, and a "down" answer is reused for 10 seconds. If the target doesn't answer, the proxy's check is `unavailable`, not `failed`. For the first request a scan does it differently: it watches the target, switches to another one and checks the affected proxies again. `--diagnose` and `--pick --verify` have no such watcher and ask directly, as for the later checks. Two things are never asked about, because the target did answer: a second site that saw a different exit IP, and a proxy that could not be connected to in the first place.

## The checks

| Name | What runs | `passed` means | It does not mean |
|---|---|---|---|
| `basic` | Handshake (HTTP, SOCKS4 or SOCKS5) and a first request to a check target that returns the caller's IP | The proxy returned a public exit IP that isn't yours | That it will answer the next request |
| `confirm` | A second request to an unrelated site (httpbin.org; ipv4.icanhazip.com when httpbin's rate limit held it back) | That site saw the same exit IP; via httpbin, the headers it received give the anonymity level | That the proxy is "safe" or that nobody logs the traffic. Via ipv4.icanhazip.com: the anonymity level, which stays unknown |
| `content` | A static test page over plain HTTP (httpbin.org/html; example.com or info.cern.ch when httpbin's rate limit held it back), compared with its hash as fetched directly | The page arrived byte for byte | That other pages arrive unchanged, or that HTTPS pages are handled the same way |
| `https` | A tunnel to the check target on port 443 with a TLS handshake that verifies | A verified TLS connection to that one host worked through the proxy at that time | Anything about other sites, later connections or who runs the proxy. What protects an `https://` page is your own client checking certificates – leave that on |

A failed check is a measurement, not a verdict about the operator. `exit_ip_mismatch` can be a rotating pool or a proxy that fakes the first answer. `content_mismatch` can be an injected script, an ad, a portal page or a copy that was cut off. The check doesn't tell which, and every such result says so in its `limits`.

## What a check looks like

```json
"checked_at": "2026-10-13T18:02:11+00:00",
"checks": {
  "basic":   {"state": "passed", "target": "checkip.amazonaws.com:80", "at": "2026-10-13T18:02:11+00:00", "ms": 412,
              "data": {"exit_ip": "203.0.113.20"}},
  "confirm": {"state": "passed", "target": "httpbin.org:80", "at": "2026-10-13T18:02:12+00:00", "ms": 655,
              "data": {"exit_ip": "203.0.113.20", "anonymity": "elite"}},
  "content": {"state": "passed", "target": "httpbin.org:80/html", "at": "2026-10-13T18:02:12+00:00", "ms": 590,
              "data": {"bytes": 3741}},
  "https":   {"state": "failed", "reason": "tunnel_refused", "target": "checkip.amazonaws.com:443",
              "at": "2026-10-13T18:02:13+00:00", "ms": 301}
}
```

| Field | |
|---|---|
| `state` | always there |
| `reason` | a code from the table below; absent for `passed` |
| `target` | what was contacted through the proxy |
| `at` | when the check finished, ISO 8601 in UTC. `checked_at` on the proxy is the time of its basic check |
| `ms` | how long it took |
| `data` | what was measured: exit IPs, anonymity, sizes; for a changed page its size, the first 16 hex digits of its SHA-256 and how many `<script` tags it contains |
| `limits` | what the result does not say |

A check that is missing from `checks` never got that far.

## Reason codes

| Code | State | Meaning |
|---|---|---|
| `connect_timeout` | failed | no TCP connection to the proxy within the time limit |
| `connect_refused` | failed | the proxy's port refused the connection |
| `connect_failed` | failed | the proxy's address could not be reached |
| `known_unreachable` | failed | this address already failed to connect earlier in the same run |
| `handshake_refused` | failed | the proxy answered, but refused the handshake or the connection to the target |
| `timeout` | failed | the proxy accepted the connection but did not answer in time |
| `connection_closed` | failed | the proxy closed the connection before a complete answer |
| `connection_error` | failed | the connection through the proxy broke |
| `bad_status` | failed | the answer through the proxy had an HTTP status other than 200 |
| `no_answer` | failed | the connection through the proxy ended before a complete HTTP response head arrived (up to 1.32.0 this was part of `bad_status`) |
| `invalid_response` | failed | the answer was not what the target sends |
| `private_exit_ip` | failed | the exit IP is a private or reserved address – the proxy answered by itself |
| `own_ip_exposed` | failed | the target saw this machine's own IP |
| `exit_ip_mismatch` | failed | the second site saw a different exit IP than the first |
| `content_mismatch` | failed | the static test page arrived with different bytes than the reference |
| `tunnel_refused` | failed | the proxy did not open a tunnel to the HTTPS target |
| `tls_certificate_invalid` | failed | the certificate inside the tunnel did not verify |
| `tls_error` | failed | the TLS handshake inside the tunnel failed |
| `target_not_configured` | unavailable | the check target did not answer when the run started, so the check never ran |
| `target_unreachable` | unavailable | the check target did not answer directly either while this was checked (any of the four checks) |
| `target_rate_limited` | unavailable | the second target (httpbin.org) refused the request with HTTP 429 and its rate-limit headers, also when asked again after its `Retry-After`; or the request was not sent because its exit IP had no free slot within 30 s (second and content request) |
| `no_reference` | unavailable | there was no reference page to compare with |
| `local_resource_limit` | unavailable | this machine ran out of sockets or file descriptors |
| `fast_mode` | skipped | left out with `--fast` |
| `filtered_out` | skipped | a filter had already ruled this proxy out |
| `earlier_check_failed` | skipped | an earlier check did not pass (in `--diagnose` and `--pick --verify` output) |

For the content check, a timeout or an error page is `unavailable` with the connection's reason code: no page came back, so nothing was compared.

httpbin.org answers HTTP 429 above 17 requests per second per client IP, and many free proxies share one exit IP. So the second and the content request are spaced to at most 8 per second per exit IP across all proxies of a run; waiting for a slot doesn't count against the proxy's time limit and lasts at most 30 seconds. A request whose slot is further away than that is not sent: the check is `unavailable:target_rate_limited` at once. A 429 is asked once more after the target's `Retry-After` (at most 3 seconds). If the target still refuses, and its answer carries rate-limit headers (`RateLimit-Policy`, `RateLimit`, `X-RateLimit-*`), the check is `unavailable:target_rate_limited`. A bare 429 without them may be the proxy's own and stays `failed:bad_status`; so does a 503, which can't be told apart from the proxy's own.

### Fallback targets

A second or content request that httpbin.org's rate limit held back (`target_rate_limited`, either way above) is sent once more through the same proxy to a fallback target, and the check records that target in `target`:

| Check | Fallback target | What it proves | What it does not give |
|---|---|---|---|
| `confirm` | `http://ipv4.icanhazip.com/` – its whole answer is the caller's IPv4 address and a newline | The same as via httpbin: a second, unrelated site saw the same exit IP. Another address is `failed:exit_ip_mismatch`, any other wrong answer fails with the usual reason codes | The anonymity level: the echo shows no request headers, so `anonymity` stays empty (`elite.txt` doesn't list the proxy) and the check's `limits` say so. Nothing is guessed |
| `content` | `http://example.com/`, or `http://info.cern.ch/` if example.com did not answer when the run started | The same as via httpbin: the page arrived byte for byte as fetched directly (over verified HTTPS) at the start of the run. Different bytes are `failed:content_mismatch` | – |

The fallback targets are asked directly once when a run starts. Without an IP address from the echo, or without a reference page from either site, there is no fallback for that check and it stays `unavailable:target_rate_limited`. A failed fallback request is checked against the fallback target asked directly, like the other later checks. Each fallback target has its own pacing of 20 requests per second per exit IP; if that is overbooked too, or the fallback answers 429 with rate-limit headers, the check stays `unavailable:target_rate_limited` (with the fallback as its `target`). Only the overflow goes there – a few hundred requests an hour in the hourly run. ipv4.icanhazip.com (Cloudflare) documents no limit; example.com is IANA's, served best effort and not meant for production use, which is why it has a reserve. In a measurement on 11 Nov 2026, 39 parallel requests through 13 proxies sharing one exit got 78 of 78 HTTP 429 from httpbin.org, and 78 of 78 correct answers from each fallback target.

The second and the content request go to a proxy that has just answered the first one, so a connection that doesn't come about there is more often a lost packet than a dead proxy. They connect with at least 6 seconds (more if `--connect-timeout` is higher); the time they get after the connect stays the same, so their whole limit grows by the difference (12 seconds instead of 10 in the hourly run, `--timeout 10 --connect-timeout 4`). A request that failed in transport – `connect_timeout`, `timeout`, `connection_closed` or `no_answer` – is tried once more after 1.5 seconds, through the same pacing and 429 handling; the check records only how the last try ended. An answer that was the problem – another exit IP, a status other than 200, a wrong or changed page – is not tried again. Worst case, a proxy's second request can take about 40.5 seconds in the hourly run (three tries of 12 seconds, the pause and a `Retry-After`), plus the wait for its slot; so can the content request.

**Second chance.** If the second or the content request still broke off in transport (the same four reasons), nothing is recorded yet: at the end of the run, at least 20 seconds after that try, the proxy gets both requests once more, and then counts with whatever they end as – once per check, as in any other run. Free proxies drop connections for a while and come back: in an A/B run on 12 Nov 2026 (two runners at the same time, 150,000 candidates each) 296 of 828 proxies passed on their second chance, and the list grew from 768 to 986 proxies. `checks.second_chance` in `run.json` says how the second chances ended (`passed`: the proxy is in the results). A proxy still waiting for its second chance when a run stops (`--want` reached, Ctrl+C) counts as checked and unconfirmed: it did fail a follow-up.

## What a list requires

| Where | `basic` | `confirm` | `content` | `https` |
|---|---|---|---|---|
| Your own run: `results/…/all.txt`, `proxies.json` | passed | passed **or unavailable** | passed **or unavailable** | any |
| `--https-only`, `https.txt` of the hourly list | passed | as above / passed | as above / passed | **passed** |
| The hourly list: `all.txt`, `http.txt`, `socks4.txt`, `socks5.txt`, `elite.txt`, `stable.txt` | passed | **passed** | **passed** | any |
| `--pick N --verify` | passed | **passed** | **passed** | passed with `--https-only` |

Your own run keeps a proxy whose second request could not run, because the alternative is an empty result whenever httpbin.org has a bad minute. It tells you: a note at the end of the run, and `unavailable` in the files. Filter on `checks.confirm.state` if you need more.

The published list is stricter. Only measured passes are listed, `stats.json` says so in `requires`, and `held_back` counts the hits that lacked one. If the second target was down for part of a run, the list is shorter by those. A run with fewer than 20 measured passes publishes nothing: the previous list stays online and its `updated` time shows its age.

## What a run records

Every run writes `run.json` next to its results, and the hourly list publishes it:

```json
{"schema": 1, "version": "1.30.0", "started": "…", "finished": "…",
 "targets": {"basic": "checkip.amazonaws.com", "basic_switches": [], "confirm": "httpbin.org", "content_reference": true,
             "confirm_fallback": "ipv4.icanhazip.com", "content_fallback": "example.com"},
 "candidates": 150000, "checked": 150000, "not_checked": 0, "no_verdict_local": 0, "stopped": null,
 "working": 1104, "kept": 1104,
 "checks": {"basic": {"failed:connect_refused": 30122, "failed:connect_timeout": 101220, "passed": 2391},
            "confirm": {"failed:bad_status": 919, "failed:exit_ip_mismatch": 311, "passed": 1161},
            "content": {"failed:content_mismatch": 57, "passed": 1104},
            "https": {"failed:tunnel_refused": 398, "passed": 706},
            "second_chance": {"failed": 532, "passed": 296}},
 "fallback": {"tried": 4210, "found": 52},
 "changed_pages": {"with_script_tag": 21, "without_script_tag": 36}}
```

The numbers in this example are made up to show the shape. `candidates` are the proxies the run set out to check, `checked` the ones that got a verdict, `not_checked` the rest (stopped by `--want` or Ctrl+C, or this machine ran out of sockets: `no_verdict_local`). `changed_pages` splits the content mismatches by whether the page that came back contains a `<script` tag; the reference page has none. `basic` counts attempts: a proxy that is checked again after a check target switch counts once per try. An address that is tried as another protocol because the listed one answered wrongly (see [how it works](how-it-works.md)) is counted apart: `fallback.tried` such checks ran, `fallback.found` of them passed, and `checks.fallback` (present when any ran) says how they ended. A proxy found that way is in `working` under the protocol it speaks; the listed key counts as checked and failed. `fallback` and `checks.fallback` are new after 1.33.0; in 1.33.0 these checks were part of `checks.basic`. `checks.second_chance` (present when a proxy got one) says how the [second chances](#reason-codes) ended – new after 1.33.1. `targets.confirm_fallback` and `targets.content_fallback` name the [fallback targets](#fallback-targets) for httpbin.org's rate limit (`null`: none this run; which proxy used one is in its check's `target`) – also new after 1.33.0.

## For code that reads the old fields

Nothing was renamed or removed. `https` is still `true`, `false` or `null`, and `anonymity` still a string. Two values changed meaning, both towards saying less:

- `https` is `null` when the HTTPS test could not run (its target was down, or this machine ran out of sockets). It used to be `false`.
- `anonymity` is `""` for a proxy whose second request could not run. That was already the case; now `checks.confirm.state` tells you why.

`proxies.csv`, a run's own and the hourly list's, has five new columns, all at the end so the old ones keep their position: `checked_at`, then `check_basic`, `check_confirm`, `check_content` and `check_https` with values like `passed` or `unavailable:target_unreachable`.

Lists published before 1.30 have neither `checks` nor `checked_at`. Readers treat that as "not recorded", not as passed.

## Exit codes of the commands that check a few proxies

| Command | 0 | 1 | 3 | 2 | 130 |
|---|---|---|---|---|---|
| `--pick N` | at least one proxy matched | none matched, or the list could not be loaded | – | bad arguments | interrupted, nothing printed |
| `--pick N --verify` | N proxies passed | none passed, or nothing could be checked | fewer than N passed (they are printed) | bad arguments | interrupted, nothing printed |
| `--diagnose PROXY` | reached and nothing failed | a check failed, or no check target could be reached from this machine | nothing failed, but a check was `unavailable` | not a proxy | interrupted |

`--pick --verify` tries 5 candidates per proxy asked for (at least 10, at most 60), up to 8 at a time (twice the number asked for, if that is less), and stops checking after 90 seconds. Loading the list and asking the check targets directly comes before that and takes a few seconds more. Among the proxies that passed, the ones higher on the list are printed. A proxy that passes was checked seconds ago from your network against the targets above. That is all it promises.
