Skip to content

Axios Proxy in Node.js: Configuration, Auth, Rotation and SOCKS5

Routing Axios traffic through a proxy is a small configuration change with a surprising number of failure modes. This guide walks through the working patterns: a basic host/port proxy, authenticated proxies via proxy.auth, rotation across a pool, SOCKS5 through an agent, environment-variable driven configuration, and the errors you are most likely to hit. Code samples are provided as protected modules and should be treated as the exact contract for each pattern.

Quick answer

Pass a proxy object with host and port into the Axios request config. If the proxy requires credentials, add an auth object with username and password. Verify the change by requesting an IP-echo endpoint such as ipify or httpbin/ip: a successful proxy request returns the proxy's IP, not your machine's. If the response still shows your own IP, re-check host, port and credentials before changing anything else.

Set up Node.js and Axios

Install a current Node.js LTS release, confirm node and npm are on your PATH, create a project folder, run npm init -y, and install Axios. If you use ES module import syntax, set "type": "module" in package.json; otherwise Node will warn or require a .mjs extension. Run a plain request first (for example to httpbin.org/get) so you know Axios works before adding a proxy.

Basic proxy with host and port

The simplest configuration is a proxy object containing host and port. Add a timeout so a dead or overloaded proxy fails fast instead of hanging. Test against an IP-echo endpoint: if the printed address matches the proxy, the route is working. If it matches your own machine, the proxy was not used.

Authenticated proxies and proxy.auth

For proxies that require credentials, add auth: { username, password } inside the proxy object. Keep secrets out of source files by reading them from environment variables and converting the port to a number. When credentials are missing or wrong, the proxy responds with 407 Proxy Authentication Required. Catch that status explicitly so the failure is distinguishable from a network error.

Common setup mistakes

Most basic proxy failures come from a small set of causes: an HTTP-only proxy asked to tunnel HTTPS (CONNECT) traffic; a typo in host or port; outbound ports such as 8080 or 3128 blocked by a corporate or cloud firewall; missing or incorrect auth credentials; or, when calling a managed scraping API, a missing or invalid API key that produces 401 Unauthorized rather than a proxy-level error.

Rotating proxies

Rotation spreads requests across multiple IPs so a single address is not hammered into rate limits or blocks. With Axios, rotation is just swapping the proxy object per request. Keep a proxy list in a separate module, then choose a strategy: random selection is simple and unpredictable; round-robin is predictable and uses every proxy evenly; power-of-two-choices picks two candidates and uses the one with fewer in-flight requests, which balances load better. A small circuit breaker that benches repeatedly failing proxies and a single backup retry keep throughput steady.

Environment variables

Axios does not read HTTP_PROXY or HTTPS_PROXY automatically. You can read those variables in Node, parse them with the URL constructor, and build a proxy object yourself. This keeps credentials out of the repository and makes switching proxies a configuration change rather than a code change. NO_PROXY can be used to exclude specific hosts.

SOCKS5 with socks-proxy-agent

Axios's built-in proxy option expects an HTTP proxy. For SOCKS4 or SOCKS5, install socks-proxy-agent and pass an instance as both httpAgent and httpsAgent. Set proxy: false so Axios does not also pick up environment proxies. When credentials contain special characters such as @ or :, encode them with encodeURIComponent before building the proxy URL; the URL constructor decodes them again when parsing.

Datacenter vs residential proxies

Datacenter proxies are fast, cheap and plentiful, but their IPs come from cloud providers and are easy for sites to detect and block at scale. Residential proxies use consumer ISP addresses, look like ordinary users, and are harder to block, but they are slower and more expensive. A practical rule: use datacenter proxies for scale and low-risk targets; use residential proxies when the target is picky about IPs.

Performance tips

A proxy adds a network hop, so expect some slowdown. Set a timeout on every request. Add retry logic (axios-retry or a small loop) for flaky proxies. Keep request payloads lean. Use an agent with keepAlive: true so repeated requests reuse TCP connections. And spread load across multiple proxies rather than overloading a single one.

Security tips

Avoid free proxy lists: many are dead, slow, or actively hostile, and some log or inject traffic. Prefer HTTPS-capable proxies so credentials and cookies are not visible to the proxy owner. Never hardcode usernames, passwords or API keys in source files; use environment variables or an uncommitted config file. Watch for header leaks such as X-Forwarded-For that can reveal your original IP. Test a new proxy pool on a small request before sending large volumes.

When not to use a proxy

Skip the proxy when you are calling a public API designed for developers, when your machine is already behind a VPN that masks your IP, when the target has no geo restrictions relevant to you, or when you are calling internal or private services on your own network. In those cases a proxy adds latency and complexity without benefit.

Troubleshooting

ECONNREFUSED or a timeout usually means Axios could not reach the proxy: check host and port, confirm the proxy is online, and test from a different network if outbound ports are blocked. A 407 means the proxy rejected your credentials. A 401 from a managed scraping API usually means the API key is missing or wrong. If a site filters bot-like traffic, set a browser-style User-Agent header. VPNs can conflict with proxies and cause DNS errors or bypasses; disable the VPN temporarily to isolate the cause.

Axios proxy field map
FieldTypeRequiredPurpose
proxy.hoststringyesProxy hostname or IP
proxy.portnumberyesProxy port
proxy.auth.usernamestringonly if proxy requires authProxy username
proxy.auth.passwordstringonly if proxy requires authProxy password
httpAgent / httpsAgentAgent instancefor SOCKS4/SOCKS5Tunnel requests through a SOCKS agent
proxy: falsebooleanwith SOCKS agentPrevent Axios from also using environment proxies

Field names and types reflect the supplied Axios examples; consult the Axios documentation for the current version.

Failure distinction checklist
SymptomLikely causeFirst check
407Proxy rejected credentialsproxy.auth.username and proxy.auth.password
ECONNREFUSEDProxy unreachable or wrong host/portHost, port, provider status
TimeoutProxy hanging or outbound port blockedTimeout value, firewall rules
401 (managed API)API key missing or wrongAPI key parameter
Own IP returnedProxy not usedproxy object present in request config

Status codes are standard HTTP semantics; the mapping to causes reflects the supplied examples.

Rotation strategy comparison
StrategyLoad balancePredictabilityBest for
RandomBasicLowSimple scripts
Round-robinEven across all proxiesHighSmall pools with healthy proxies
Power of two choices + circuit breakerBetter than randomMediumLarger pools with flaky proxies

Qualitative comparison based on the supplied rotation examples; no benchmark data is implied.

Frequently asked questions

What is Axios and why does proxy configuration matter?

Axios is a widely used HTTP client for Node.js and browsers with promise-based requests. Configuring a proxy lets you mask your IP, reach geo-restricted content, reduce rate-limit pressure, and test how your app behaves under different network conditions.

How do I set up a basic proxy with Axios?

Add a proxy object with host and port to the request config. The target site then sees the proxy's IP rather than yours. Confirm with an IP-echo endpoint.

Can I use authenticated proxies with Axios?

Yes. Put username and password inside proxy.auth. If the credentials are wrong or missing, the proxy returns 407 Proxy Authentication Required.

What are rotating proxies and why are they useful?

Rotation switches the IP used per request across a pool. That spreads traffic, lowers ban risk, and helps with large-scale scraping or rate limits.

Can I use SOCKS5 proxies with Axios?

Not through the built-in proxy option. Install socks-proxy-agent and pass it as both httpAgent and httpsAgent to tunnel requests through a SOCKS5 server.

{
  "name": "axios-proxy-demo",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "axios": "^1.12.2"
  }
}