Timeouts, 429s, 502s and other proxy errors

Short version: before you fix anything, work out which leg failed: your machine to the proxy, the proxy to the site, or the site itself. curl -v usually tells you in one run.

curl -sv -o /dev/null --proxy "http://HOST:PORT" --proxy-user 'USERNAME:PASSWORD' https://api.ipify.org

If you see 200 Connection established, the proxy let you in, and anything that goes wrong after that line is between you and the site.

Connection refused

Something said no before any HTTP happened. Nearly always the proxy address in your config.

1. Compare the host and port with the proxy's Connection card, character by character.
2. Print the host and port your code actually uses. An unset environment variable can leave it pointing at your own machine.
3. Check the proxy is still Active in the dashboard.
4. Company networks and some hosting providers block outbound ports. If curl is refused from the same machine too, it's the address or your network.

Timeout

Nothing came back in time.

1. Set separate connect and read timeouts. Around 10 seconds to connect and 30 to read is a fair start. Whichever fires tells you which leg is slow.
2. On residential, retry once: the retry leaves from a different home connection. Keep it to one or two.
3. In a headless browser, block images, fonts and video you don't need. Fewer bytes, fewer stalls, a smaller meter.
4. If curl times out from the same machine, a firewall or VPN on your side may be blocking proxy ports.

429 Too Many Requests

The site says you're going too fast. Your credentials are fine.

1. Honour Retry-After if it's there. Retrying sooner tends to make the block longer.
2. Cap how many requests hit one domain at once.
3. Back off exponentially, with a bit of random jitter, and give up after a few tries.
4. If the limit is per IP and your overall pace is reasonable, rotating residential, once it's on sale, spreads requests over many addresses. One static IP will get rate-limited eventually.

502 Bad Gateway and 503 Service Unavailable

Read when it arrived. In reply to the CONNECT, it's the proxy path. Inside the tunnel, it's the site.

1. Open the site without the proxy. Down for everyone? Wait it out.
2. Retry once or twice with a pause. On residential, a retry leaves through a different exit.
3. A 503 that's really a challenge page is a block. Treat it like a 403: see Got a 407 or a 403? Here's what they mean.
4. Check Service status in the dashboard sidebar for open incidents. Nothing there and proxy-side errors keep coming? Use Report an issue on the proxy, or email support@proxymonkey.io your curl -v output with the password removed.

SSL "wrong version number"

Your client tried TLS against a proxy that speaks plain HTTP. Write the proxy URL as http://, even for https:// sites. The traffic to the site is still encrypted inside the tunnel. Check HTTPS_PROXY in your shell profile or CI config too.

Connection reset (ECONNRESET)

Usually a pooled connection that sat idle too long. Retry safe requests (GETs) once on a fresh connection, keep your client's idle limit short, and put a deadline on every request.

Still stuck? Send what Blocked by a site? Send us this lists. Longer write-ups for each error are in our proxy error guide.