Skip to content
Fixedmark

Networking · 11 min read

Updated

Proxy Error Codes Explained: 407, 403, 502, 503

First find out who answered. If the status is the reply to `CONNECT`, the proxy refused the tunnel, and your HTTP client raises an error with no response. If `CONNECT` returned `200` and the error came after, the destination answered and you get a normal response. 407 is always the proxy. 502, 503, and 504 on CONNECT mean the proxy could not reach the destination.

On this page

Who answered, the proxy or the destination

Every proxy failure sorts into two piles. Either the proxy refused to build the tunnel, or the tunnel worked and the server at the far end said no. The fixes never overlap, so sort first.

For an https:// URL, your client sends CONNECT host:443 to the proxy and waits for a status line. RFC 9110 says any 2xx reply means the proxy has switched to tunnel mode, and "any response other than a successful response indicates that the tunnel has not yet been formed." Anything after a 200 comes from the destination. The HTTP CONNECT explainer walks through those bytes.

curl -v shows both replies. Here is a refusal from a local test proxy, run with curl 8.21.0.

Terminal
$ curl -v --proxy http://demo:s3cret@127.0.0.1:38471 https://denied.test/
* Establishing HTTP proxy tunnel to denied.test:443
> CONNECT denied.test:443 HTTP/1.1
> Host: denied.test:443
> Proxy-Authorization: Basic ZGVtbzpzM2NyZXQ=
>
< HTTP/1.1 403 Forbidden
< Proxy-Status: toy; error=http_request_denied
< Content-Length: 0
<
* CONNECT tunnel failed, response 403
curl: (7) CONNECT tunnel failed, response 403

And here is a 403 from the destination, after the tunnel opened.

Terminal (trimmed)
$ curl -v --proxy http://demo:s3cret@127.0.0.1:38471 https://httpbin.org/status/403 -o /dev/null
> CONNECT httpbin.org:443 HTTP/1.1
< HTTP/1.1 200 Connection Established
* CONNECT tunnel established, response 200
> GET /status/403 HTTP/2
< HTTP/2 403

For scripts, curl prints both codes on one line. The curl man page defines http_connect as the code "found in the last response (from a proxy) to a curl CONNECT request."

Terminal
$ curl -sS -o /dev/null -w 'proxy=%{http_connect} dest=%{http_code}\n' \
    --proxy "$PROXY_URL" https://httpbin.org/status/403
proxy=200 dest=403

$ curl -sS -o /dev/null -w 'proxy=%{http_connect} dest=%{http_code}\n' \
    --proxy "$PROXY_URL" https://denied.test/
curl: (7) CONNECT tunnel failed, response 403
proxy=403 dest=000

dest=000 means no response came from the destination. The exit code for a refused CONNECT depends on the curl version. curl 8.21.0, used for the captures here, exits with code 7, and its own test 749 expects 7. Other releases report the same refusal as error 56, and old ones printed `Received HTTP code 403 from proxy after CONNECT`. Match on the status number in the message, not the exit code.

Plain http:// destinations are the exception. There is no CONNECT, so a proxy's 403 and a server's 403 look alike. Look for a Via, Proxy-Status, or vendor header, or test with an https:// URL.

407 Proxy Authentication Required

A 407 always comes from a proxy, never from the API you are calling. RFC 9110 says it means "the client needs to authenticate itself in order to use a proxy for this request."

The usual causes are dull. Check them in this order.

  1. No credentials were sent. curl -v shows a Proxy-Authorization line under CONNECT. If curl works and your app gets a 407, its client drops them. Java's HttpClient disables Basic auth for tunnels by default (see the Java guide).
  2. The credentials are wrong or revoked. Copy the proxy URL again instead of retyping it.
  3. A password character breaks the URL. Percent-encode @, :, /, and %, so p@ss becomes p%40ss.
  4. The variable holds quotes or a trailing newline. Log its length, not its value.
  5. One deploy still has a rotated-out credential. See rotating credentials without downtime.

A proxy can also answer 407 when an account is over quota or suspended. Fixedmark's planned quota behavior does this, as the last section shows.

403 from the proxy vs 403 from the destination

RFC 9110 defines 403 as a server that "understood the request but refuses to fulfill it," and adds that "a request might be forbidden for reasons unrelated to the credentials." That covers both piles.

When the proxy sends it

A 403 in reply to CONNECT means your credentials were fine and the proxy's policy blocked this destination. These are the typical policies.

  • Port restrictions. RFC 9110 says proxies "SHOULD restrict its use to a limited set of known ports." The curl book notes that most HTTP proxies allow only port 443 "and perhaps a few others," so a CONNECT to port 5432, 22, or 25 often fails.
  • A per-credential destination allowlist that does not name this host and port.
  • Blocklists of abusive networks.

Fix it on the proxy side. Add the exact host:port to the credential's allowlist.

When the destination sends it

A 403 after 200 Connection Established means the proxy did its job. For an API that allowlists IPs, these are the usual reasons.

  • The request left from an IP the partner has not added. If your proxy uses a pair of IPs, both must be on the list.
  • The request skipped the proxy, often through a NO_PROXY rule or a library that ignores proxy variables.
  • The allowlist change has not taken effect yet.
  • The API rejects something else, such as an API key or a client certificate. The body usually says which.

Indian broker APIs have their own IP mismatch errors.

502, 503, and 504 on CONNECT

A 5xx in reply to CONNECT means the proxy tried to reach the destination and failed. Your request never got there. RFC 9110 defines all three in terms of gateways and proxies.

5xx codes a proxy sends on CONNECT, per RFC 9110
CodeRFC 9110 meaningWhat it usually means for a tunnel
502 Bad GatewayThe proxy "received an invalid response from an inbound server"DNS for the host failed, the connection was refused, or the route does not exist
503 Service UnavailableA "temporary overload or scheduled maintenance"; may carry Retry-AfterThe proxy is overloaded, at a connection limit, or marks the destination as down
504 Gateway TimeoutNo "timely response from an upstream server"The TCP connection to the destination never completed

Proxies disagree on these mappings. An operator reported that a CONNECT to a nonexistent domain got a 503 on Squid 4.13 and a 500 on Squid 5.8. A Squid maintainer called the change unintentional and pointed to RFC 9209, which recommends 502.

RFC 9209 defines the Proxy-Status header, which names the exact failure, such as Proxy-Status: ExampleCDN; error=connection_timeout. Its registry pairs each error type with a recommended status.

Selected RFC 9209 proxy error types
`error=`MeaningRecommended status
dns_errorDNS lookup for the next hop failed502
dns_timeoutDNS lookup timed out504
connection_refusedThe next hop refused the connection502
connection_timeoutOpening the connection timed out504
destination_ip_prohibitedPolicy forbids the next hop's IP502
destination_unavailableThe next hop is considered down503
connection_limit_reachedToo many connections to the next hop503
http_request_deniedPolicy rejected the request403

Support for Proxy-Status varies, but read every header on a refused CONNECT. A proxy's own error header is often more specific than the code.

A 502 usually means a wrong host or port, a private-only host name, or a server that is down. A 503 with Retry-After is worth a retry after that delay. A 504 usually means the destination's firewall silently drops traffic from the proxy's IP. Databases and MongoDB Atlas behave this way.

The SOCKS5 equivalents

SOCKS5 replies with a one-byte code instead. RFC 1928 defines nine values.

SOCKS5 reply codes, RFC 1928 section 6
CodeMeaning
0x00Succeeded
0x01General SOCKS server failure
0x02Connection not allowed by ruleset (the 403 equivalent)
0x03Network unreachable
0x04Host unreachable
0x05Connection refused
0x06TTL expired
0x07Command not supported
0x08Address type not supported

Wrong credentials fail earlier. Under RFC 1929, the server returns a non-zero status and "MUST close the connection." curl reports SOCKS failures as CURLE_PROXY, exit code 97, a "proxy handshake error" in the libcurl error list. With socks5://, a DNS failure happens on your machine, not the proxy. See socks5 vs socks5h.

TLS errors through a proxy

A request can run two TLS sessions. The outer one goes to the proxy, and exists only with an https:// proxy URL. The inner one goes to the destination, inside the tunnel. Each error belongs to one of them.

The proxy URL's scheme does not match the port

These two mistakes produce the strangest messages.

Terminal
# https:// proxy URL, but the port speaks plain HTTP
$ curl -sS --proxy https://demo:s3cret@127.0.0.1:38480 https://example.com/
curl: (35) TLS connect error: error:0A00010B:SSL routines::wrong version number

# http:// proxy URL, but the port expects TLS first
$ curl -sS --proxy http://demo:s3cret@127.0.0.1:38443 https://example.com/
curl: (56) Proxy CONNECT aborted

In the first, curl sent a TLS ClientHello and got plain text back. In the second, the TLS listener hung up on a plain CONNECT. Go reports that as unexpected EOF, and Python requests as RemoteDisconnected. Match the scheme to the port. HTTPS proxy endpoints covers which clients support https:// proxy URLs.

Certificate errors on each hop

An outer-hop error names the proxy. Go prefixes it with proxyconnect, as in proxyconnect tcp: tls: failed to verify certificate: x509: certificate signed by unknown authority. An inner-hop error appears after CONNECT tunnel established in curl -v.

curl trusts the hops separately. --proxy-cacert verifies the proxy, and --cacert the destination. A corporate TLS inspection box shows up as your company's CA on the outer hop. An outdated CA bundle in an old container image can break both, so update ca-certificates.

Timeouts, and which phase stalled

A timeout through a proxy can stall in four places, and the error rarely says which.

  1. TCP to the proxy. The host is down, the port is wrong, or your own firewall blocks it.
  2. The CONNECT reply. The proxy is still trying to reach the destination.
  3. TLS with the destination, inside the tunnel.
  4. The response. The API itself is slow.

curl counts the first two as the connection, with one message for both. Here a proxy never answered CONNECT, then the proxy address was unroutable.

Terminal
$ curl -sS --connect-timeout 3 --proxy "$PROXY_URL" https://hang.test/
curl: (28) Connection timed out after 3002 milliseconds

$ curl -sS --connect-timeout 3 --proxy http://demo:s3cret@10.255.255.1:38471 https://example.com/
curl: (28) Connection timed out after 3002 milliseconds

Use -v to tell them apart. Output that stops at Trying is phase 1. A > CONNECT with no reply is phase 2. For slow requests that succeed, the timing variables help.

Terminal
$ curl -sS -o /dev/null --proxy "$PROXY_URL" \
    -w 'proxy=%{http_connect} dest=%{http_code} tcp=%{time_connect}s tls=%{time_appconnect}s first_byte=%{time_starttransfer}s\n' \
    https://example.com/
proxy=200 dest=200 tcp=0.000086s tls=0.010407s first_byte=0.017775s

time_connect is TCP to the proxy. time_appconnect ends when TLS with the destination completes, so it includes the CONNECT round trip. A big gap between them covers CONNECT and the TLS handshake through the tunnel. A big gap after time_appconnect is the API's own time.

Libraries label phases their own way. Against the silent proxy, Python requests with timeout=(3, 5) raised ReadTimeout ... (read timeout=3), and Go printed Client.Timeout exceeded while awaiting headers. Set explicit timeouts in every client, since several defaults wait forever.

Error strings by client

Captured with curl 8.21.0, requests 2.34.2, undici 8.12.4 on Node.js 26, and Go 1.26. Wording changes between versions, so search logs for the distinctive part.

What each client reports for common proxy failures
FailurecurlPython requestsNode.js undiciGo net/http
407 on CONNECT(7) CONNECT tunnel failed, response 407Tunnel connection failed: 407 Proxy Authentication RequiredProxy response (407) !== 200 when HTTP TunnelingProxy Authentication Required
403 on CONNECT(7) CONNECT tunnel failed, response 403Tunnel connection failed: 403 ForbiddenProxy response (403) !== 200 when HTTP TunnelingForbidden
502 on CONNECT(7) CONNECT tunnel failed, response 502Tunnel connection failed: 502 Bad GatewayProxy response (502) !== 200 when HTTP TunnelingBad Gateway
Proxy port closed(7) Failed to connect to ... over proxy[Errno 111] Connection refusedECONNREFUSEDproxyconnect tcp: dial tcp ...: connection refused
403 from the destinationExit 0, http_code 403A normal responseA normal responseA normal response

undici, which backs Node's fetch, buries the reason. The error says fetch failed, its cause says Request was cancelled., and the proxy status sits one cause deeper. Go returns only the reason phrase, so a log line ending : Forbidden is the proxy, not the API.

In code, a proxy refusal is an exception and a destination refusal is a response. Handle them in separate branches so your logs say which side failed.

import os
import requests

PROXY = os.environ["PROXY_URL"]
session = requests.Session()
session.proxies = {"http": PROXY, "https": PROXY}


def call(url: str) -> None:
    try:
        res = session.get(url, timeout=(5, 30))
    except requests.exceptions.ProxyError as e:
        # The proxy refused the tunnel or could not be reached. No response exists.
        print("proxy side:", e)
        return
    except requests.exceptions.Timeout as e:
        print("timed out, check which phase:", e)
        return
    if res.status_code in (401, 403):
        # The tunnel worked. The destination said no.
        print("destination side:", res.status_code)
        return
    print("ok:", res.status_code)

The Node.js check matches text from undici's ProxyAgent, and the Go check the proxyconnect operation in net/http. Both are implementation details, so pin versions and keep a test.

A debugging checklist with curl -v

  1. 1
    Reproduce with curl where the app runsUse the app's proxy URL, from the same container if you can. If curl works and the app fails, the app's client config is the problem.
  2. 2
    Read the line after CONNECTNon-200 is the proxy. Read its headers for Proxy-Status or a vendor error. A 200 means look at TLS or the destination.
  3. 3
    Check the egress IPCall an IP echo endpoint, like the What's my IP tool, through the same client, several times. Compare with the partner's allowlist.
  4. 4
    Find the TLS hop or the timeout phaseErrors before CONNECT, or with Go's proxyconnect prefix, are the proxy hop. Stalls after > CONNECT are the proxy reaching the destination.
  5. 5
    Retry only what is safeA refused CONNECT never reached the destination. A timeout or reset after sending may have, so retry only idempotent calls.

Doing this with Fixedmark

Fixedmark is a static outbound IP proxy in early access. Its proxy is planned to add an X-Proxy-Error header to several refusals. These values are planned launch behavior from the troubleshooting and limits docs and may change.

Planned Fixedmark proxy replies
ReplyMeaning
407The app ID or token is wrong, revoked, or not URL-encoded
403 with X-Proxy-Error: denied_by_policyThe token's destination allowlist does not name this host and port
429 or 407 with X-Proxy-Error: quota_exceededThe plan's bandwidth quota and its soft margin are used up. See limits
X-Proxy-Error: smtp_blocked_by_provider or smtp_deniedPort 25 is blocked, or ports 465 and 587 are not enabled for the account yet
SOCKS5 reply 0x02The SOCKS5 equivalent of denied_by_policy

Port 443 expects TLS first, so an http:// proxy URL aimed at it fails like the mismatch above. Ports 8080 and 1080 are plain, for clients that cannot do TLS (concepts).

Every connection leaves a row in the connection logs with a result such as auth_failed, denied_by_policy, upstream_unreachable, upstream_timeout, or upstream_reset. The upstream results record what happened between the proxy and the destination, which answers the 5xx questions. The API filters by result.

Terminal
curl "https://api.fixedmark.com/v1/apps/APP_ID/logs?direction=egress&result=upstream_timeout&limit=100" \
  -H "Authorization: Bearer $FIXEDMARK_API_KEY"

If some connections to one host end in upstream_timeout while others succeed, one of your two IPs is probably missing from its allowlist. Compare the egress_ip on the failing rows with the rows that succeed, then verify your egress IP and add both.

Sources

Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.

Blog

Frequently asked questions

Is a 407 error from the proxy or the website?

Always the proxy. It wants credentials it did not get or did not accept.

How do I tell if a 403 came from the proxy or the destination?

Run `curl -v` and read the reply to `CONNECT`. A 403 there is the proxy. A 200 there followed by a 403 is the destination.

What does 502 Bad Gateway mean on a CONNECT request?

The proxy could not connect to the destination, usually because of a DNS failure, a refused connection, or a wrong port. Your request never reached the server.

Why does curl say CONNECT tunnel failed?

The proxy answered CONNECT with a non-200 status, printed at the end of the message. The exit code depends on the curl version, 7 on curl 8.21.0 and 56 on others, so read the status number instead.

Why does my request time out only through the proxy?

Usually the destination's firewall silently drops packets from an IP it does not allow. Put every proxy egress IP on its allowlist.

Make it fixed.

Fixedmark is in early access. Join the list to get dedicated static IPs when your region opens.