How to Connect to a Residential Proxy: Host, Port and Format

Connecting to a residential proxy is a five-minute job that regularly takes an afternoon, usually because the documentation for one provider assumes conventions from another. There are only four moving parts: a host, a port, a username, and a password. What varies between providers is how much meaning gets packed into the username, and on a gateway like this one that is where nearly everything lives.

Here is the format, what each piece does, and how to read the errors when something is off.

The four parts

Part	Value
Host	p.shifter.io
Port	443
Username	customer-USERNAME plus optional targeting flags
Password	from the panel

The host and port never change. Not for a different country, not for a sticky session, not for SOCKS5 instead of HTTP. Every request goes to the same endpoint, and what you want is expressed in the username. That is the single most important thing to understand, because it is what differs most from older port-based products where each configuration meant a different address.

Both HTTP(S) and SOCKS5 speak to the same host and port. Your credentials are in the panel under Residential Proxies.

The simplest possible request

Start here and confirm it works before adding anything:

curl -x customer-USERNAME:PASSWORD@p.shifter.io:443 https://ipinfo.io/json

That returns JSON describing the exit address you were given. Run it twice and you should see two different addresses, because rotation is the default. If that works, your credentials are correct and everything else is configuration.

Adding targeting to the username

Flags are appended to the username with hyphens. Order does not matter, values are lowercase, and multi-word values use underscores.

customer-USERNAME                                   # rotate, no geo
customer-USERNAME-country-de                        # German exit
customer-USERNAME-country-us-city-new_york          # city level
customer-USERNAME-country-us-asn-7922               # specific network
customer-USERNAME-sid-abc123                        # sticky session
customer-USERNAME-sid-abc123-ttl-600                # sticky for 10 minutes
customer-USERNAME-country-gb-sid-abc123-ttl-600     # combined

Country codes are ISO 3166-1 alpha-2, so the United Kingdom is gb rather than uk, which is the single most common typo. sid is any string you choose and holds the same exit address for subsequent requests; ttl sets how long in seconds and is only valid alongside sid, defaulting to 120. The full reference is in the geo-targeting docs and sessions docs, and the conceptual difference is in sticky versus rotating.

One useful extra: by default, if nothing matches a very narrow filter at that moment, the gateway falls back to a broader pool so your request still completes. Add strict-true when an exact geo match matters more than the request succeeding, and you will get a 502 instead of a silent fallback.

The two formats you will meet

Proxy credentials get written two ways, and converting between them trips people up.

URL form, used by most libraries and by curl:

http://customer-USERNAME-country-de:PASSWORD@p.shifter.io:443

Colon-separated form, used by many desktop tools and browser extensions, which usually want the parts in separate fields:

p.shifter.io:443:customer-USERNAME-country-de:PASSWORD

They carry identical information. If a tool asks for four fields, use the second layout; if it asks for one string, use the first.

In code

import requests

USER = "customer-USERNAME-country-de"
PROXY = f"http://{USER}:PASSWORD@p.shifter.io:443"

r = requests.get("https://ipinfo.io/json",
                 proxies={"http": PROXY, "https": PROXY}, timeout=20)
print(r.json())

Set both the http and https entries. Setting only one is a common cause of “it works for some requests and not others”, because plain and secure requests take different paths.

If your password contains characters that are meaningful in a URL, such as @, :, / or #, percent-encode it before embedding, or the URL parses wrongly and you get an authentication error with entirely correct credentials.

For SOCKS5, keep the same host, port and credentials and change the scheme. Use the variant that resolves hostnames at the proxy rather than locally, since the other one leaks your DNS and can return regionally wrong results, which is covered in preventing DNS leaks.

Working configurations for other stacks are in the integrations docs and, for Python specifically, in using residential proxies with Python.

Reading the errors

Four responses cover almost every setup problem, and each points somewhere different.

407 Proxy Authentication Required means the gateway rejected your credentials. Either they are wrong, or a flag in your username is malformed, because an unrecognised value makes the whole username unparseable. Strip every flag and test the bare username first: if that works, the fault is in the flags, and you can add them back one at a time to find it. The full diagnostic path is in fixing 407 and credential errors.

502 Bad Gateway means your credentials were fine but nothing matched your filter at that moment. Broaden it, drop from city to country, or remove strict-true.

509 Bandwidth Limit Exceeded means the plan allocation is exhausted with overage disabled. Nothing is wrong with the connection.

Connection refused or a timeout means you never reached the gateway. Check that you are pointing at p.shifter.io:443 rather than a legacy port-based host, and test raw connectivity with nc -vz p.shifter.io 443 before assuming a proxy problem.

Verifying it is actually working

Two checks worth running once at the start.

Confirm rotation: send the same request several times with no sid and confirm the address changes. If it does not, the usual cause is your HTTP client reusing one connection rather than the proxy failing to rotate, which is covered in IP not rotating.

Confirm geography: request a country and check that the returned address geolocates there, and more meaningfully that a geo-sensitive target behaves as though you are there. The fuller method is in testing speed, success rate and location accuracy.

The bottom line

One host, one port, everything else in the username. Get a bare request working first, then add targeting flags one at a time, and remember that country codes are ISO so the UK is gb. Set both the HTTP and HTTPS proxy entries, percent-encode a password with special characters, and use the SOCKS5 variant that resolves remotely if you go that route. When something fails, the status code tells you where to look: 407 is credentials or a malformed flag, 502 is a filter with nothing behind it, 509 is bandwidth, and connection refused means you are not talking to the gateway at all.

That gateway is the front door to residential proxies, where country, city, ASN and session are all parameters on the same connection, billed per GB so nothing about your configuration changes what you pay. If you are new to all of this, start with residential proxies for beginners.