407 Proxy Authentication Required: what it means and how to fix it

A 407 comes from a proxy, not the website. Why it appears in browsers, curl and CI jobs, how it differs from 401, and how to send proxy credentials correctly.

· 6 min read · By the Spot Downtime team

407 Proxy Authentication Required means a proxy server sits between the client and the website, and that proxy wants credentials before it forwards the request. The website itself never saw the request. That is the single most useful fact about a 407: the problem is in the proxy configuration, not in the site you were trying to reach.

407 versus 401

The two codes look alike but come from different machines and use different headers.

  • 401 comes from the origin server. It sends WWW-Authenticate, and the client answers with an Authorization header. See 401 Unauthorized.
  • 407 comes from a proxy. It sends Proxy-Authenticate, and the client answers with a Proxy-Authorization header.

Because they use separate headers, a request can need both: proxy credentials to get out through the corporate network, and an API key to get in at the destination. Sending one does not satisfy the other.

Where you will see it

  • Corporate or school networks. A browser or tool is set to use a proxy that requires a login, and the saved password is missing, expired or wrong.
  • CI runners and containers. npm install, pip, apt or docker pull fail with a 407 because the build environment has HTTP_PROXY set but without credentials.
  • Outbound proxies for scraping or API calls. A paid or self-hosted forward proxy rejects requests whose credentials or IP allowlist entry are wrong.
  • Tunnelling HTTPS. For https URLs the client sends CONNECT host:443 to the proxy first, and the 407 comes back on that CONNECT request. Tools often report this as a failed tunnel rather than a plain 407.

Reading the response

A 407 response must include a Proxy-Authenticate header listing the schemes the proxy accepts. Check it with curl, which shows what the proxy answered:

bash
curl -v -x http://proxy.example.com:3128 https://example.com/

< HTTP/1.1 407 Proxy Authentication Required
< Proxy-Authenticate: Basic realm="corp-proxy"

Basic means a username and password sent base64-encoded. NTLM, Negotiate or Kerberos point to a Windows domain proxy, where credentials come from the logged-in user and a plain username and password in the URL often won't work.

Fixes

Send credentials to the proxy

With curl, give the proxy credentials separately from any credentials for the destination:

bash
# Proxy credentials
curl -x http://proxy.example.com:3128 --proxy-user "alice:s3cret" https://example.com/

# Windows domain proxy using NTLM or Negotiate
curl -x http://proxy.example.com:3128 --proxy-user "DOMAIN\\alice:s3cret" --proxy-ntlm https://example.com/

In environment variables, put the credentials in the proxy URL. Special characters in the password must be percent-encoded, so @ becomes %40 and : becomes %3A. An unencoded @ in a password is a very common reason a correct password is still rejected.

bash
export HTTPS_PROXY="http://alice:p%[email protected]:3128"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

Tool-specific settings

Many tools ignore the environment variables and need their own configuration:

bash
# npm
npm config set proxy http://alice:p%[email protected]:3128
npm config set https-proxy http://alice:p%[email protected]:3128

# pip
pip install --proxy http://alice:p%[email protected]:3128 requests

# git
git config --global http.proxy http://alice:p%[email protected]:3128

For the Docker daemon, proxy settings belong in the systemd unit or daemon.json, not in your shell, because the daemon makes the pulls.

Bypass the proxy for hosts that should not use it

If an internal host or a metadata address is going through the proxy by mistake, the proxy may demand credentials for something it can't reach anyway. Add those hosts to NO_PROXY. Support for wildcards and CIDR ranges in that variable differs between tools, so prefer plain domain suffixes like .internal.example.com.

Check the allowlist

Some proxy services authenticate by source IP instead of, or in addition to, a password. If the machine's public IP changed (a new cloud instance, a different NAT gateway), the proxy treats it as unauthenticated and returns 407.

Don't retry a 407 in a loop

A 407 will not fix itself. Automatic retries with the same missing credentials just generate more failed logins, and on some proxies repeated failures lock the account. Treat it like a 401: fix the credentials, then retry.

If you run the proxy

When users report 407s that you did not expect, check these first:

  • Whether the credential store (LDAP, a password file, an identity provider) is reachable from the proxy itself.
  • Whether a password expiry or rotation happened recently for the shared account clients use.
  • Whether a new client uses a scheme the proxy does not offer, for example Negotiate against a proxy configured only for Basic.
  • Whether the 407 comes on the CONNECT request in the proxy log, which means HTTPS traffic is the one being blocked.

Does this matter for uptime monitoring?

Rarely for the monitored site, since a public website should not return a 407 to visitors. If a monitor does report one, the response came from something in the path that you may not know about, such as a reverse proxy or security gateway in front of the site, and visitors on the same path would hit it too. If your own jobs call out through a proxy, a 407 in their logs is better caught early. A heartbeat monitor on a scheduled job that depends on the proxy will tell you when it stops completing, even if the job itself only logs the error.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading