Proxy problems feel varied when you are in the middle of one and are actually quite repetitive. Nearly everything that goes wrong falls into eight 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 |
|---|---|---|
407 Proxy Authentication Required | Wrong credentials, or a malformed flag in the username | Test the bare username with no flags |
502 Bad Gateway | No addresses matched your filter at that moment | Broaden the filter |
509 Bandwidth Limit Exceeded | Plan allocation exhausted, overage disabled | Check the wallet and plan |
| Connection refused or hang | You never reached the gateway | nc -vz p.shifter.io 443 |
| Timeouts | Target slowness, over-tight filter, or your own concurrency | Split connect time from read time |
403 or a challenge page | The target rejected the identity, not the proxy | Retire the session, check headers |
200 with wrong or empty content | A soft block, or the wrong locale | Validate the body, check geo signals |
| Same IP every request | Almost always connection reuse in your client | Test with separate processes |
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 443If 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.comA 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.
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 https://ipinfo.io/json | head -c 60; echo
doneIf 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.
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.
The bottom line
Eight 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 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.