407 Proxy Authentication Required: Every Cause and Its Fix

The reason 407 is worth its own page is that the error message points in the wrong direction for most people. It arrives while you are fetching a website, it looks like an HTTP error from that website, and the natural next step — change the target, change the headers, rotate the exit — is wasted effort every single time.

Confirm it in one command

Before touching application code, take the application out of the picture entirely.

Run curl -x http://USER:PASS@HOST:PORT https://api.ipify.org and read the result. An IP address means the proxy accepted your credentials and the problem is in your client. Another 407 means the credentials, the plan or the endpoint is wrong, and no client change will help.

The eight causes, in order of frequency

1. A typo, or a character the shell ate

Proxy passwords often contain @, : and #, all of which are meaningful inside a URL. A password containing @ splits the URL at the wrong point and sends half of it as a hostname. URL-encode the credentials, or pass them with a dedicated flag such as curl's -U user:pass instead of embedding them.

2. The client never sends proxy credentials

Plenty of tools accept a proxy URL and quietly discard the userinfo part. Chromium is the significant one: --proxy-server takes no credentials at all, which is why Puppeteer and Playwright need an explicit authentication step rather than a URL. Anything built on Chromium inherits the same gap.

3. IP authentication and a changed address

Whitelist authentication works until your public address moves — a router reboot, a new office, a cloud instance recycled onto a different address, a VPN toggled on. Nothing in the error says so. Check your current address against the allowlist first; our IP tool shows what the proxy actually sees.

4. Mixing the two authentication modes

Most providers, including us, expect one mode per sub-user: either credentials or an allowlisted address. Configuring an allowlist and then also sending a username can be read as a mismatch rather than as belt and braces.

5. Wrong port for the protocol

HTTP and SOCKS5 endpoints usually listen on different ports. Pointing a SOCKS client at the HTTP port produces a confusing mixture of 407s and connection resets rather than a clean protocol error.

6. An expired plan or exhausted balance

Correct credentials against an inactive plan are still refused, and the status code does not distinguish the two. Check the dashboard before assuming a configuration fault.

7. Session syntax in the username

Sticky sessions and geo-targeting are commonly encoded in the username — country, session id, TTL, separated by a delimiter. A typo in that string is a bad username, not a bad option, and comes back as 407. Generate it rather than hand-editing it.

8. An intermediary stripping the header

Corporate networks, VPN clients and some container runtimes rewrite or drop Proxy-Authorization. If curl succeeds on your machine and fails from a build agent with the same credentials, suspect the path rather than the payload.

Language-specific traps

Telling 407 apart from its neighbours

Stopping it happening again

• Keep credentials in environment variables, never inline in the code that gets copied between projects.
• URL-encode at build time rather than trusting the shell, the YAML parser and the client to agree.
• Prefer credential authentication anywhere the source address can change — laptops, CI runners, autoscaling workers.
• Give each workload its own sub-user, so a rotated password takes down one job instead of all of them.
• Treat a first 407 in production as a credentials incident, not a transient error, and skip the retry loop.

Once the curl test passes, everything left is client behaviour, and client behaviour is documented. That is why 407 is the error worth fixing properly the first time: unlike a block, it never comes back on its own.