Axios Proxy Setup in Node.js: HTTP and SOCKS5
Choose Axios proxy configuration or a SOCKS agent deliberately, control environment overrides and verify request routing without exposing credentials.
KAIROXO
Axios proxy configuration is most predictable when each request has one clear routing owner. In Node.js, an HTTP proxy can be configured through Axios itself, while a SOCKS5 connection normally uses a compatible agent. Combining both mechanisms unintentionally can produce a route that differs from the one shown in a developer's configuration file.
Begin with a small diagnostic request before adding application cookies, parallel workers or a large target list. This guide focuses on the Node.js runtime: browser-side JavaScript has different networking restrictions, and copying this configuration into a frontend bundle does not give a browser a configurable outbound proxy.
Gather the actual connection values
Obtain the gateway scheme, hostname, port and credentials from the selected KAIROXO product. Keep the target URL separate from the proxy URL. A request to an HTTPS website may travel through an HTTP proxy tunnel, so select the gateway protocol from its documentation rather than deriving it from the target.
The example expects PROXY_URL in the local process environment. If it includes credentials, percent-encode the username and password components separately when constructing it. Characters such as @, : and / otherwise change URL parsing. Avoid placing the complete value in shell history, screenshots, issue reports or general application logs.
Implementation steps
Choose the HTTP or SOCKS route
Install Axios and socks-proxy-agent in a small Node.js project, using a supported Node release and the package versions your integration has verified. The example imports both packages so it can demonstrate the two branches in one file. An HTTP-only service can omit the SOCKS dependency after choosing its configuration.
For HTTP or HTTPS gateways, Axios receives a protocol, host, port and optional auth object. For SOCKS5, a SocksProxyAgent supplies the underlying connection and proxy:false prevents Axios from adding its own proxy layer. This distinction is particularly important on machines that already define HTTP_PROXY or HTTPS_PROXY for other tools.
Codejavascript import axios from 'axios'import {SocksProxyAgent} from 'socks-proxy-agent'const required = name => { const value = process.env[name] if (!value) throw new Error('Missing ' + name) return value}const endpoint = new URL(required('PROXY_URL'))const config = {timeout:15000,signal:AbortSignal.timeout(20000),maxRedirects:0,maxContentLength:65536}if (['socks5:', 'socks5h:'].includes(endpoint.protocol)) { const agent = new SocksProxyAgent(endpoint) config.httpAgent = agent config.httpsAgent = agent config.proxy = false} else if (['http:', 'https:'].includes(endpoint.protocol)) { config.proxy = { protocol: endpoint.protocol.slice(0,-1), host: endpoint.hostname, port: Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)), ...(endpoint.username ? {auth:{ username:decodeURIComponent(endpoint.username), password:decodeURIComponent(endpoint.password) }} : {}) }} else throw new Error('Unsupported proxy protocol')try { const response = await axios.get('https://httpbin.org/ip',config) if (typeof response.data?.origin !== 'string') throw new Error('Unexpected diagnostic response') // Inspect origin locally; do not print endpoint, config or entire errors. console.log({status:response.status,diagnosticShapeValid:true})} catch (error) { console.error({code:error.code || 'DIAGNOSTIC_FAILED',status:error.response?.status}) process.exitCode = 1}Control DNS and environment assumptions
With socks-proxy-agent, socks5 and socks5h express different hostname-resolution behavior: the latter requests proxy-side resolution. Choose deliberately, then verify that the gateway and the environment support it. Moving DNS resolution changes one part of the route; it does not automatically prove that every process, subrequest or system resolver follows the same path.
Review HTTP_PROXY, HTTPS_PROXY and NO_PROXY when comparing machines. For the HTTP branch, an explicit Axios proxy object establishes the intended configuration; for the SOCKS branch, the explicit agent and proxy:false keep Axios's environment-based proxy selection out of that connection. Do not leave unexplained bypass rules in a repeatability test.
Verify response shape and actual exit
Run the sample against the public diagnostic endpoint, inspect the origin value locally and compare the result with the access profile. The printed status and shape flag intentionally avoid publishing the exit or credentials. A correct shape is useful for detecting an HTML error document, but geography and session behavior need their own checks.
Test from the runtime that will perform the work. A host terminal, a container and a scheduled job can have different DNS, proxy variables and outbound policies. After the diagnostic succeeds, make one request to an authorized target and confirm the exact content fields you need. Keep redirects disabled for this first inspection so an unexpected destination is visible.
Set bounded time and size policies
The Axios timeout and AbortSignal provide finite request deadlines with different implementation details; test their behavior on the adapter and Node version you deploy. The example also limits redirects and response size. These are small diagnostic defaults, not recommended limits for every data task.
For real workloads, define whether cancellation includes download, parsing and downstream persistence. Stream large responses when appropriate and place a clear maximum on accepted data. If an error occurs, log a sanitized category and status rather than serializing the Axios error: its request configuration can contain proxy authentication. Keep full diagnostic inspection local and temporary.
Reuse resources and budget retries
A persistent worker should reuse an appropriate agent instead of constructing a new pool for each URL. Configure pool behavior intentionally and measure cold versus warm requests. Close resources when shutting down the worker. A keep-alive connection is a transport detail; it does not promise a stable residential exit when the provider's rotation policy selects a different route.
Retry safe operations with an attempt limit and delay, accounting for the total elapsed budget. Review 407 as a proxy-authentication problem and treat 429 according to the destination's rate policy. Avoid stacking retries in the queue, HTTP wrapper and job scheduler without a shared limit. Three independent retry loops can multiply traffic far beyond the number of jobs you intended.