Fixing "407 Proxy Authentication Required"
A 407 means the proxy rejected your credentials before the request left. Work through the seven causes, from quoting bugs to whitelist conflicts.
A 407 Proxy Authentication Required comes from the proxy, not the website. Your request stopped at our edge because the credentials attached to it were missing, malformed, or not valid for the endpoint you sent them to. Almost every cause is local to your machine or your account, and each has a check you can run in a minute. The exception: a correct password can also get a 407 while the gateway cannot reach its authentication service, or when one source address sends more logins than the gateway's per-source limits allow. If a credential that worked minutes ago starts failing and nothing changed on your side, pause, retry, and check the status page before changing anything.
First, reproduce it outside your application
Strip the problem to a single command before changing any code:
curl -v -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org- It prints an IP address. Your credentials and the proxy are fine; the bug is in how your application passes proxy settings. Go to cause 6.
- It prints
407. The credentials themselves are being rejected. Work through causes 1 to 5, then 7. - It hangs or prints
Connection refused. Not an authentication problem. See connection issues.
Keep the -v flag: curl prints the Proxy-Authorization header it actually sent, which is often not the one you thought you were sending.
Cause 1: the endpoint belongs to a product your account does not hold
Symptom: the credential is correct and works on one host but not another.
Every proxy credential on your account works on every product the account holds an active plan for (a free account has 1 credential set; paid accounts can create up to 5). Sent to a gateway you hold no plan for, it is refused with a 407 that looks exactly like a wrong password. The usual cases: a free account pointed at the rotating or residential gateway (the free tier is static shared datacenter, HTTP only), or a plan that has lapsed.
Check: open Plans and confirm an active plan for the product whose host you are connecting to. Then copy the host and port from that product's row on the Proxies page rather than from an older config. Authentication covers which credential goes where.
Cause 2: special characters in the password
Symptom: the password contains @, :, /, # or %, and curl -v shows a username or host you did not intend.
In a proxy URL those characters have structural meaning. A password of p@ss:word in http://user:p@ss:word@host:port is parsed as username user, password p, and hostname ss:word@host.
Fix: percent-encode the password (@ becomes %40, : becomes %3A, / becomes %2F, # becomes %23, % becomes %25):
# password is p@ss:word
curl -x http://USERNAME:p%40ss%3Aword@HOST:PORT https://api.ipify.orgOr pass the credentials separately, which curl accepts verbatim:
curl -x http://HOST:PORT -U 'USERNAME:p@ss:word' https://api.ipify.orgIn code, use the language's URL-encoding function (encodeURIComponent in JavaScript, urllib.parse.quote in Python) rather than encoding by hand, which is how a % in an already-encoded password gets encoded twice.
Cause 3: invisible characters from copy and paste
Symptom: the credential looks right in an editor and still fails.
A value copied from a web page, chat client or PDF can carry a trailing newline, a non-breaking space, a zero-width character or a curly quote. None of them are visible; all of them change the password.
Check:
# Reveal exactly what is in the variable, including characters that do not print
printf '%q\n' "$PROXY_PASSWORD"Anything beyond the characters you expect (\r, \n, a stray space) is the cause. Retype the value by hand once to confirm, then fix whatever introduced it. .env files preserve a trailing space after the value in most parsers.
Cause 4: the whitelist and your source address disagree
Symptom: a setup with no username configured worked for days and now fails, often after a reboot, an outage or overnight.
Node4 has two authentication modes, and they are alternatives rather than layers. With IP whitelisting, available on every product, you register your public address and connect with no credentials (on residential, a whitelisted connection carries no username and so gets an untargeted exit). If your source address has changed (a new office, a rebuilt container, a reassigned VPS, a home line that rotated overnight), requests now arrive from an address the whitelist has never seen, there are no credentials to fall back on, and the proxy answers 407.
Check: find your current address from the machine that carries the traffic, then compare it with Account Settings → Auth & IP Access in the dashboard:
curl -s https://api.ipify.orgA free account may whitelist 1 address; paid plans include 3. If your address changes often, username and password authentication is the more stable choice. IP whitelisting best practices covers the environments where the whitelist holds up.
Cause 5: a targeting segment typo on a gateway product
Symptom: the bare credential works, but a username with -country- or -session- segments fails.
Residential and rotating gateway products carry targeting in the username, as in USERNAME-country-us. On the rotating gateways a misspelled key straight after the username, as in USERNAME-contry-us, stays part of the username, so the credential no longer matches and the answer is a 407. On residential a misspelled key never reaches this guide's 407: it is a 400 Bad Request whose body names the unknown option and lists the valid ones, with an X-Node4-Targeting: unknown-key header (SOCKS5 has no status line, so there it gets the same refusal as a wrong password, with no key named). A malformed value for a known key is a 407 on residential. The rules that bite most often:
- The country code is two letters:
us,gb,de. Notusa,ukoren. - Separators are single hyphens; a double hyphen leaves an empty segment.
- Segment keywords are lowercase.
- A city is written without spaces or punctuation:
newyork, notNew Yorkornew-york.
The rotating gateways are looser, and a mistake there is not always a 407. A bad country value such as usa is a 502, and so is a misspelled key after the country segment, because the country code then includes the misspelled option (USERNAME-country-us-sesion-x asks for US-SESION-X). A misspelled key after a session segment becomes part of the session id, and the request is served from an untargeted exit with no error. Keep the order username, country, session, and check the exit after any change; the typo examples show each case.
A well-formed location with no available exits is a different failure: the gateway answers 502 with a plain-text reason (and an X-Node4-Targeting header on residential) rather than a 407, and never silently serves another country. A city name that exists in more than one state is refused the same way until you add the state, as in USERNAME-country-co-state-dc-city-bogota for Bogota, Colombia. Those cases are covered in country and city targeting.
Check: drop every segment and connect with the bare username. If that works, the problem is in the segments; country and city targeting has the full grammar.
Cause 6: the library is not sending the credentials you configured
Symptom: curl works, your application gets 407.
Python requests applies credentials from the proxy URL correctly, but a proxy in the environment (HTTPS_PROXY or HTTP_PROXY) outranks the matching session.proxies entry, so an old credential left in a CI runner or container can produce the 407 while your code holds the right one. A per-request proxies= argument outranks the environment; so does setting session.trust_env = False:
import requests
proxies = {
"http": "http://USERNAME:PASSWORD@HOST:PORT",
"https": "http://USERNAME:PASSWORD@HOST:PORT",
}
r = requests.get("https://api.ipify.org", proxies=proxies, timeout=30)
print(r.text)The https entry uses an http:// scheme. That is correct: it describes how to reach the proxy, not how the proxy reaches the target.
Node's fetch and axios do not read proxy settings from a URL the way curl does, and axios before 1.16.1 sent HTTPS requests to its proxy option without a tunnel. The axios proxy guide and Node.js proxy setup cover the current approach.
Headless browsers: Chromium accepts a proxy server on the command line but not credentials, and instead fires an authentication event the script has to answer. A headless script that never answers it fails every navigation with net::ERR_INVALID_AUTH_CREDENTIALS; one that answers with wrong credentials can see a 407 status instead. Puppeteer and Playwright covers both.
Anti-detect browsers store the credential per profile, so a 407 on one profile while others work is checked in that profile's own proxy fields; the AdsPower, BitBrowser and Hubstudio setup guides show where they are.
Cause 7: the account cannot authenticate right now
Symptom: everything above checks out and the credential still fails everywhere.
- A lapsed subscription stops authenticating rather than silently serving traffic. Subscription state is on Plans.
- A plan that has used its data allowance stops at the cap, and the refusal is a
407. On the free tier (1 GB a month) access returns when the month resets, and a paid plan brings its own allowance. On a paid Shared Datacenter, Rotating Datacenter or residential plan, a bandwidth top-up restores it for the rest of the billing period; otherwise it returns at renewal. Usage against the allowance is on the Dashboard, with per-proxy history on Analytics. - An email address that was never verified has no proxies provisioned, so its credentials match nothing. The Dashboard and Proxies pages show a banner until it is confirmed.
Not a 407: a 403 from the residential gateway
A 403 from the residential gateway means the credential was accepted and the destination was not. The residential network does not serve government sites and some payment and advertising sites, so a request to one of them is refused whatever the username, country or session says. The response body says which case you hit:
destination not available on residential proxies(plain HTTP): the network's own refusal was recognized, so the cause is known. Retrying or changing country will not help; use a datacenter proxy for that site.destination refused by the residential network(HTTPS, through aCONNECTtunnel): the gateway sees only the refusal status, not its reason, so it names the likely cause. If other sites fail the same way at the same moment, it is a temporary problem on the residential network rather than the destination: retry later.
Checklist
- Reproduce with curl. If curl works, the bug is in the application.
- Confirm the account holds an active plan for the host you are calling.
- Percent-encode the password, or pass it with
-U. - Check for invisible characters with
printf '%q'. - If using the whitelist, compare your current public address with the entries.
- Strip targeting segments back to the bare username.
- Check the account is verified, in credit and inside its allowance.
If the error persists after all seven, open a ticket from the dashboard with the verbose curl output (password redacted) and the exact host and port. That output usually identifies the cause at once.
Not yet on a plan? The free tier provisions 3 free shared proxies with 1 GB/month bandwidth and 10 concurrent threads, enough to confirm a credential and a target work together.
