Proxy error codes: which hop sent it and how to fix it

Originally published on proxymint.

Proxy error codes decoded by hop: which ones the proxy sends, which come from the target, how to read them with curl -v, and which ones are safe to retry.

TL;DR

• The hop matters more than the number. A request through a proxy crosses the client, the gateway, the exit and the target, and the same 502 means different things depending on which one sent it.
• curl -v shows the phase. On an https:// target an error that answers the CONNECT came from the proxy side; anything after 200 Connection established came from the target.
• Some failures have no status code. Refused connections, timeouts and SOCKS5 replies surface as client errors such as curl exit codes 5, 7, 28, 56 and 97.
• Retry only what can pass. 429, 503 and gateway-phase 502 or 504 are worth a backoff or a new exit; 400, 407 and refused connections are setup errors.

Key takeaways

• Run the failing request with curl -v first. It tells you whether the error came back on the CONNECT or inside the tunnel, which decides who can fix it.
• Read Proxy-Status and Retry-After when present. RFC 9209 lets a gateway name the failing hop and cause; Retry-After tells you how long to wait on 429 and 503.
• Fail fast on 400, 407 and refused connections. Log the exact proxy string and error, fix the setting, and keep these out of the retry loop.
• Treat repeated 403s as a fit question. Slow down, check the target terms and API, and match the proxy category to the network type the target accepts.

Read the full guide on proxymint, with the commands, tables and sources.