Troubleshooting
Proxy errors explained
Proxy errors are easier to fix once you know which machine produced them. These pages cover the errors we see most often in support, with the commands we actually use to diagnose them.
Each one is written to be read when something is broken: the answer first, the reasoning after.
- Errors covered
- 6
- Written from
- Real support cases
Every error, and what it actually means
Each page explains who is sending the error, how to tell it apart from the ones it resembles, and the commands that narrow it down. They are written from real support cases rather than from a specification.
- 407 Proxy Authentication RequiredA 407 means the proxy received your request and rejected the username or password. The network path is fine; the credentials are not.
- 403 Forbidden when using a proxyA 403 comes from the website, not the proxy. The request arrived and the site decided to refuse it, usually because of what the request looked like rather than where it came from.
- 429 Too Many RequestsA 429 is rate limiting. The site understood the request and is telling you to slow down. Unlike a 403, it is usually about timing rather than identity.
- Proxy connection timed outA timeout means nothing answered. No status code came back at all, which points at the network path, the hostname or the port rather than at credentials or content.
- ERR_PROXY_CONNECTION_FAILEDA Chrome-family error shown when the browser cannot reach the configured proxy at all. It is a browser-side message, so the cause is usually in the proxy settings rather than on the network.
- 502 Bad Gateway through a proxyA 502 through a proxy is ambiguous: it can come from the proxy failing to reach the target, or from the target's own infrastructure. Telling them apart is the whole task.
Work out who is refusing you first
Most time lost to proxy errors is spent fixing the wrong layer. The single most useful question is which machine produced the message, because that eliminates most of the possibilities before you change anything.
A 407 comes from the proxy and concerns your credentials. A 403 or 429 comes from the target website, which means the proxy already did its job. A timeout means nobody answered at all, so the problem sits below HTTP entirely. ERR_PROXY_CONNECTION_FAILED is generated by your own browser and never leaves your machine.
Once you know the layer, the fix is usually short. Changing a proxy password will never fix a 403, and tuning headers will never fix a 407.
The four places a request can fail
A proxied request passes through more hands than a direct one, and each hand can refuse it in its own way. Knowing the order makes the error messages far less confusing.
First your own machine has to resolve the proxy hostname and open a connection to it. Failures here never produce a status code, because nothing has answered yet; this is where timeouts and browser-level errors live. Second the proxy decides whether to accept you, which is where a 407 comes from and the only stage that concerns your credentials.
Third the proxy tries to reach the destination on your behalf. A failure here can surface as a 502, because the proxy is acting as a gateway and reporting that the thing behind it did not answer properly. Fourth the destination itself decides what to do with the request, which is where 403 and 429 are decided, long after the proxy has done its job correctly.
Reading an error against that sequence usually tells you which half of the system to look at, and saves changing settings that were never involved.
Reading the status code itself
HTTP status codes are grouped by their first digit, and that grouping is a shortcut worth knowing. Anything in the 400s means the request was understood and rejected, so the fault is attributed to the caller. Anything in the 500s means the server accepted the request and then failed to fulfil it, so the fault is on their side.
That single distinction answers the most common question people have when a scraping job starts failing, which is whether to change their own code or wait. A page of 403s is a signal to change something about the request. A page of 502s usually means waiting, because nothing you send will help a broken upstream.
The exception is 429, which sits in the 400s but behaves like a conversation rather than a refusal. It is the one error that routinely tells you exactly what to do next, in a Retry-After header, and the one most often ignored.
A thirty second triage
Run the request through the proxy with curl and look only at what comes back. A status code means something answered you, so the network is fine and the question is who objected. No status code at all means the request never completed, which points at DNS, the port, or a path that is blocked.
curl -sS -o /dev/null -w 'status: %{http_code} connect: %{time_connect}s total: %{time_total}s\n' \
--proxy proxy.example.com:8000 --proxy-user 'USER:PASS' \
--max-time 30 https://example.comFrequently asked questions
How do I tell a proxy problem from a site problem?
Look at who answered. A 407 is the proxy. A 403 or 429 is the website, which means the proxy worked. A timeout means nothing answered at all.
Which error means my credentials are wrong?
407 Proxy Authentication Required. No other error in this list is about credentials.
Which error means the site is blocking me?
403 Forbidden, usually. A 429 means you are being rate limited rather than blocked outright.
Ready to try it?
Create an account, add funds from US$1 and pick your country and proxy type.