Proxy problems feel varied when you are in the middle of one and are actually quite repetitive. Nearly everything that goes wrong falls into nine patterns, and in most cases the response itself tells you which one you are looking at. This is the index: find your symptom, get the likely cause and the immediate fix, and follow the link when you need the longer version.
The quick table
| Symptom | Usually means | First thing to do | Retry? |
|---|---|---|---|
407 Proxy Authentication Required | Wrong credentials, or a malformed flag in the username | Test the bare username with no flags | Never |
502 Bad Gateway | No addresses matched your filter at that moment | Broaden the filter | Only after broadening |
509 Bandwidth Limit Exceeded | Plan allocation exhausted, overage disabled | Check the wallet and plan | No |
| Connection refused or hang | You never reached the gateway | nc -vz p.shifter.io 443 | No, fix connectivity first |
| Timeouts | Target slowness, over-tight filter, or your own concurrency | Split connect time from read time | Yes, with backoff |
403 or a challenge page | The target rejected the identity, not the proxy | Retire the session, check headers | Not on the same session |
429 Too Many Requests | The target is limiting your request rate | Honour Retry-After, then slow down | Yes, after waiting |
200 with wrong or empty content | A soft block, or the wrong locale | Validate the body, check geo signals | Not until the cause is fixed |
| Same IP every request | Almost always connection reuse in your client | Test with separate processes | Not applicable |
407: authentication rejected
The gateway declined your credentials, which means your traffic reached it and connectivity is fine.
Three causes account for nearly all of them: a typo in the credentials, a malformed flag in the extended username, or a password that was rotated in the panel while an old copy is still deployed somewhere. The middle one is the least obvious, because an unrecognised value such as country-uk instead of country-gb makes the entire username unparseable, so it is reported as an auth failure rather than a targeting error.
The diagnostic is always the same: strip every flag and test the bare username first. If that succeeds, the fault is in the flags and you add them back one at a time. If it fails, re-copy the password from the panel. Full detail in fixing 407 and credential errors.
Never retry a 407. It is terminal, and a retry loop against it burns bandwidth while looking like credential stuffing from the outside.
502: nothing matched your filter
Your credentials were accepted and then no address was available for the combination you asked for. This is a targeting problem, not a fault.
It usually appears when a filter is very narrow, a small city, a specific ASN, or a combination of both, and it is more likely at hours when the local pool is thin, since availability follows human activity. Broaden the filter, drop from city to region or country, or remove strict matching so the gateway falls back to a broader pool. If you are relying on strict matching deliberately, this error is the system working as intended. Background in country availability.
509: out of bandwidth
The plan allocation is exhausted and overage is not enabled, so requests stop. Nothing is wrong with the connection or the configuration. Add funds to enable overage, or wait for the cycle to reset, and if this happens regularly the plan is undersized, which is a forecasting question covered in estimating monthly bandwidth.
Connection refused, or a request that hangs forever
You are not talking to the gateway at all. Two usual causes: you are pointing at a legacy port-based host rather than p.shifter.io:443, or your own network is blocking outbound traffic on that port.
Test raw connectivity before assuming anything about the proxy:
nc -vz p.shifter.io 443
If that fails, it is an egress or firewall problem on your side. If it succeeds but requests still fail, you are into the authentication path above.
Timeouts
The most ambiguous class, because several different problems produce the same symptom. The single most useful step is to separate connect time from total time, since they point in opposite directions:
curl -o /dev/null -s -w "connect: %{time_connect}s total: %{time_total}s\n" \
-x customer-USERNAME:PASSWORD@p.shifter.io:443 https://example.com
A slow connect points at the proxy path or an over-tight filter making address selection slow. A fast connect with a slow total points at the target being slow, which is not something a proxy change fixes. Also check whether your timeouts are simply tuned for datacenter latency, because residential connections are legitimately slower and a two-second timeout will fail constantly for reasons that are not errors. The full diagnostic is in why requests time out, and the tuning options are in reducing latency.
403, captchas, and challenge pages
These come from the target, not the proxy, which means authentication and connectivity both worked. The target looked at the request and declined it.
The immediate response is to retire that session and take a fresh one rather than retrying on the same identity. The durable response is to find out why, and the order of likelihood is pace first, then request shape, then behaviour, then address quality. Slowing down fixes more of these than anything else, per rate limiting and throttling, and if pace is defensible the next suspect is headers and user agent contradicting each other. The recovery playbook is in what to do when your IPs get banned.
429: too many requests
The target is rate-limiting you. Like a 403, it comes from the site rather than the gateway, so your credentials and connection are fine. It means requests are arriving faster than the site accepts from one visitor, one session or one network.
Slow down rather than retrying straight away. If the response carries a Retry-After header, wait at least that long before the next request to that site. If it does not, back off exponentially, lower concurrency for that target, and spread requests across more sessions instead of pushing more through one. Retrying a 429 at the same pace turns a temporary limit into a block. The pacing method is in the rate-limiting guide linked in the 403 section above.
A 200 that is not what you wanted
The most expensive failure, because nothing looks wrong. A challenge page, an empty result set, a truncated listing, or a generic regional page can all arrive with a success status, and a pipeline counting status codes will record them as data.
If the content is wrong rather than missing, suspect geography before anything else: an Accept-Language header that contradicts your exit country, or a DNS leak resolving hostnames from your location instead of the proxy’s, both produce plausible content for the wrong market. See matching geo, timezone and locale and preventing DNS leaks.
If the content is a challenge or a stub, treat it as a block, per detecting blocked or fake content. Either way the lesson is the same: validate the body before counting a response as a success, or none of your monitoring means anything.
The same address on every request
Rotation appears broken and almost never is. The usual cause is that your HTTP client is reusing one connection, and the exit address is chosen when the connection is established rather than per request sent down it.
Test with separate processes first:
for i in 1 2 3; do
curl -s -x customer-USERNAME:PASSWORD@p.shifter.io:443 http://ip-info.com/json | head -c 60; echo
done
If that rotates and your application does not, the cause is connection pooling in your client. If neither rotates, check for a sid flag in the username requesting a sticky session, and confirm the address you are seeing is not simply your own, which would mean the proxy is not being applied at all. Full causes in IP not rotating.
In a browser: ERR_PROXY_CONNECTION_FAILED and ERR_TUNNEL_CONNECTION_FAILED
Browsers often hide the proxy’s status code behind their own error names. Two cover most cases.
ERR_PROXY_CONNECTION_FAILEDmeans the browser could not reach the proxy at all. Treat it like connection refused above: check that the host isp.shifter.ioand the port is443, then check whether your network, firewall or antivirus is blocking the connection.ERR_TUNNEL_CONNECTION_FAILEDmeans the browser reached the proxy, but the proxy did not open the tunnel to the site. That is usually a 407 (credentials or a malformed flag) or a 502 (nothing matched your filter), so test the bare username first, as in the 407 section.
TLS and certificate errors
Less common, and usually environmental. An outdated TLS library rejecting the gateway’s cipher suite, or a corporate middlebox breaking the chain of trust. Update the client library first. Disabling certificate verification will make the error go away and should be used only to confirm the diagnosis, never in anything you ship.
A general order of operations
When something breaks and you are not sure where to start: confirm raw connectivity, then test bare credentials with no flags, then add flags back one at a time, then check whether the response is genuinely what you asked for rather than trusting the status code. That sequence isolates the layer in a couple of minutes, and it is the same sequence whether the symptom is an error code or data that looks subtly wrong.
For anything ongoing rather than acute, the instrumentation that catches these before you notice them manually is in monitoring proxy health at scale.
Frequently asked questions
Which proxy errors should I retry?
Retry timeouts with backoff, and 429s after waiting for Retry-After. Never retry a 407: it is a credentials or flag problem and retrying burns bandwidth. Broaden the filter before retrying a 502, and take a fresh session rather than retrying a 403 on the same one.
What does 502 Bad Gateway mean on a residential proxy?
Your credentials were accepted, but no address matched the targeting you asked for at that moment, usually because a city, ASN or combination is very narrow. Broaden the filter, from city to region or country, and try again.
Why does my proxy return a 200 but the wrong content?
Either it is a soft block, such as a challenge page or empty result that arrives with a success status, or the locale is wrong because an Accept-Language header or a DNS leak contradicts your exit country. Validate the body before you count a response as a success.
Why is my residential proxy using the same IP on every request?
Almost always because your HTTP client reuses one connection, and the exit address is chosen when the connection opens. Test with separate processes. If that rotates and your application does not, the cause is connection pooling; if neither rotates, check for a sid flag requesting a sticky session.
The bottom line
Nine patterns cover almost everything. 407 is credentials or a malformed flag and is never worth retrying. 502 is an empty filter rather than a fault. 509 is bandwidth. Connection refused means you never reached the gateway. Timeouts need connect time separated from total time before anything else. A 403 or challenge is the target declining you, so change identity and then find out why. A 429 is the target asking you to slow down, so honour Retry-After and reduce pace. A 200 with the wrong content is the dangerous one and is why body validation is not optional. And the same address every request is nearly always connection reuse in your own client. Work from connectivity outward, and check what came back rather than what the status code claims.
The gateway itself is documented in how to connect, the vocabulary in the glossary, and the product is residential proxies with per-GB pricing.