Axios Proxy Setup: HTTP, HTTPS, Agents, and 407 Errors

For a Node.js service that owns its routing policy, an explicit Axios instance is the least ambiguous starting point. Keep the destination URL, proxy endpoint, and proxy credentials in separate fields. The proxy protocol describes the client-to-gateway connection; an https:// destination can travel through an http proxy because Axios creates a CONNECT tunnel for the destination TLS session.

import axios from 'axios';

const client = axios.create({
  adapter: 'http',
  proxy: {
    protocol: 'http',
    host: process.env.DATABAY_PROXY_HOST,
    port: Number(process.env.DATABAY_PROXY_PORT),
    auth: {
      username: process.env.DATABAY_PROXY_USER,
      password: process.env.DATABAY_PROXY_PASS,
    },
  },
  timeout: 10_000,
  maxRedirects: 3,
  maxContentLength: 10 * 1024 * 1024,
  maxBodyLength: 1 * 1024 * 1024,
  transitional: { clarifyTimeoutError: true },
  redact: ['password', 'authorization', 'proxy-authorization'],
});

const response = await client.get(
  'https://databay.com/what-is-my-ip/json',
);
console.log(response.data);

This guide and its capture apply to Axios's Node HTTP adapter, not browser JavaScript. A browser cannot open an arbitrary forward-proxy socket through Axios request config; browser traffic is governed by the browser or operating-system proxy configuration and by origin security policy. Pin and review your Axios version. The observations below were reproduced on Axios 1.18.1 and Node 24.14.0, not assumed from older snippets.

We ran isolated listeners on 127.0.0.1 on 2026-07-27. No public proxy or public destination was contacted. The HTTPS case used the reserved name example.test and stopped immediately after the proxy response, before destination TLS. Synthetic passwords were reduced to their length in the evidence.

The sanitized Axios observation ledger preserves the full machine-readable record. It is a protocol and failure-boundary artifact, not a latency benchmark and not evidence about public proxy quality.

For an HTTP destination, the proxy needs the complete destination URL, so Axios 1.18.1 sent an absolute-form request target:

GET http://service.example/report?id=42 HTTP/1.1
Host: service.example
Proxy-Authorization: Basic <redacted>

For an HTTPS destination through the same HTTP proxy, Axios asked the proxy to open a byte tunnel:

CONNECT service.example:443 HTTP/1.1
Host: service.example:443
Proxy-Authorization: Basic <redacted>

After a successful CONNECT response, destination TLS belongs inside that tunnel. The proxy protocol and destination protocol answer different questions: proxy.protocol: 'http' does not downgrade an https:// destination. Axios 1.18.1's official request-config documentation explicitly describes this CONNECT behavior and confines Proxy-Authorization to the CONNECT request. The current release line also includes a defense-in-depth fix first shipped in 1.16.1 for a cleartext leak in some HTTPS-through-HTTP-proxy configurations, which is a concrete reason not to copy an unpinned old workaround.

If the proxy itself requires TLS, set its protocol to https and configure the proxy trust boundary deliberately. Do not set rejectUnauthorized: false as a catch-all repair; first identify whether certificate validation failed on the proxy hop or the destination hop.

Axios supports both explicit configuration and conventional environment variables. Mixing them without an ownership rule makes the route difficult to audit.

Axios also documents a newer boundary: when the selected Node agent has native proxyEnv enabled, Axios defers environment-proxy handling to Node. That branch was not enabled in our Windows lab, so treat it as an official-documentation boundary and test it on your exact Node startup flags and agents. Log only a route class such as explicit, environment, bypass, or agent; never log a credential-bearing environment value.

Axios exposes httpAgent and httpsAgent so Node applications can control connection pooling, socket limits, TLS material, and other transport behavior. A plain http.Agent does not contain a proxy address. In the lab, a plain agent plus proxy: false connected directly. With explicit proxy config, a keep-alive agent reused one client-to-proxy socket for two sequential requests.

import http from 'node:http';
import axios from 'axios';

const proxySocketPool = new http.Agent({
  keepAlive: true,
  maxSockets: 20,
  maxFreeSockets: 5,
});

const client = axios.create({
  adapter: 'http',
  proxy: {
    protocol: 'http',
    host: process.env.DATABAY_PROXY_HOST,
    port: Number(process.env.DATABAY_PROXY_PORT),
    auth: {
      username: process.env.DATABAY_PROXY_USER,
      password: process.env.DATABAY_PROXY_PASS,
    },
  },
  httpAgent: proxySocketPool,
  timeout: 10_000,
});

// Destroy a process-owned custom agent during graceful shutdown.
process.once('beforeExit', () => proxySocketPool.destroy());

Do not add a custom agent merely because an old article says modern Node lacks keep-alive. Add one when you need explicit socket limits, TLS options, instrumentation, or a third-party proxy implementation. If a custom proxy agent owns routing, follow that agent's version-pinned contract and normally set proxy: false so Axios does not apply a second proxy layer. This lab did not test SOCKS agents; use the HTTP versus SOCKS5 decision guide before selecting a different protocol.

The explicit proxy.auth object avoids URL-encoding mistakes when a password contains @, :, /, or %. Axios converted the lab's reserved-character password into the expected Basic proxy credential. The destination never received that header.

The less obvious leak surface is error logging. An AxiosError carries the request config, which can contain proxy authentication. Axios 1.18 supports a redact list for error.toJSON(). Our lab set redact: ['password'], triggered a 407 with an intentionally wrong secret, and confirmed the serialized password became [REDACTED ****].

const safeErrorClient = axios.create({
  // ...proxy and timeout config...
  redact: [
    'password',
    'authorization',
    'proxy-authorization',
    'cookie',
    'set-cookie',
  ],
});

try {
  await safeErrorClient.get('https://service.example/health');
} catch (error) {
  if (!axios.isAxiosError(error)) throw error;
  const safe = error.toJSON();
  console.error({
    name: safe.name,
    code: safe.code,
    status: error.response?.status ?? null,
    message: safe.message,
  });
}

Redaction changes serialized output; it does not erase the original request config, the process environment, or request headers. Do not dump error.config, a proxy URL, request headers, or environment variables. Retrieve production values from a secret manager, restrict their scope, and rotate them after unintended exposure.

The Axios error code alone does not identify the responsible hop. In the lab, both the proxy 407 and destination 403 used ERR_BAD_REQUEST. The status and path evidence made them different.

A response proves a component answered, not that the route is safe or authorized. The proxy request-path guide maps TCP, proxy authentication, CONNECT, destination TLS, and destination HTTP into separate evidence layers.

Axios documents no finite default timeout, and response/body size limits can be unlimited unless configured. A production request to a destination you do not fully control needs explicit budgets. The lab used a deliberately stalled proxy and confirmed that timeout: 150 with clarifyTimeoutError: true rejected as ETIMEDOUT without reaching the destination.

const client = axios.create({
  timeout: 10_000,
  maxRedirects: 3,
  maxContentLength: 10 * 1024 * 1024,
  maxBodyLength: 1 * 1024 * 1024,
  transitional: { clarifyTimeoutError: true },
});

const controller = new AbortController();
const overallBudget = setTimeout(() => controller.abort(), 15_000);

try {
  const response = await client.get('https://service.example/report', {
    signal: controller.signal,
  });
  // Consume only the fields the job needs.
  console.log(response.status);
} finally {
  clearTimeout(overallBudget);
}

A timeout and an AbortSignal answer related but different operational needs: the Axios timeout bounds request inactivity/elapsed request behavior in the adapter, while a caller-owned signal can enforce a workflow-level cancellation. Test both in your runtime. Automatic retries should be bounded and limited to authorized, idempotent work whose failure semantics are understood. Never retry or rotate automatically after 401, 403, 407, CAPTCHA, quota, or an unclear authorization boundary.

Classify only what the error proves. Avoid string matching on the full message, and do not include secret-bearing request config in logs.

import axios from 'axios';

export function classifyAxiosFailure(error) {
  if (!axios.isAxiosError(error)) {
    return { layer: 'application', retryable: false };
  }

  const status = error.response?.status;
  if (status === 407) {
    return { layer: 'proxy-auth', status, retryable: false };
  }
  if (status === 401 || status === 403) {
    return { layer: 'destination-access', status, retryable: false };
  }
  if (status === 429) {
    return { layer: 'destination-rate', status, retryable: false };
  }
  if (error.code === 'ETIMEDOUT' || error.code === 'ECONNABORTED') {
    return { layer: 'time-budget', status: null, retryable: 'policy' };
  }
  if (error.code === 'ECONNREFUSED') {
    return { layer: 'tcp-connect', status: null, retryable: false };
  }
  if (error.request && !error.response) {
    return { layer: 'no-http-response', status: null, retryable: 'investigate' };
  }
  return { layer: 'http-response', status: status ?? null, retryable: false };
}

retryable: 'policy' is intentionally not a Boolean approval. The caller still needs to know the method, whether a body may have been processed, the remaining time budget, and the source's access policy. Preserve a privacy-safe route class, attempt count, Axios version, status, and error code. Do not record the proxy username, hostname, complete destination URL, headers, response body, or cookies.

First prove the base Axios control path against an endpoint you own. Then add one documented Databay routing control at a time to the proxy username so any failure has one new variable:

# Base route
DATABAY_PROXY_USER='USER-zone-residential'

# Request a US exit estimate
DATABAY_PROXY_USER='USER-zone-residential-countryCode-us'

# Request short-lived continuity for an authorized workflow
DATABAY_PROXY_USER='USER-zone-residential-countryCode-us-sessionId-axios-qa-01'

Set DATABAY_PROXY_HOST=gw.databay.co and DATABAY_PROXY_PORT=8888, then pass the username and password through proxy.auth. A country control requests a pool selection; it does not reproduce language, cookies, account settings, GPS, device state, or every localization input. A session control requests route continuity; it is not a user identity or dedicated device.

Choose datacenter proxies for an approved workload that values infrastructure throughput, or residential proxies when the test genuinely requires a consumer-network route or country sample. Use the destination's official API, export, preview, or testing environment first when it satisfies the job.

The repository harness is designed to fail when Axios behavior drifts. From the frontend project directory, run:

npm run content:verify-axios

The command starts only localhost listeners, runs the asserted cases, prints the observation ledger, and refreshes public/data/axios-proxy-lab-2026-07-27.json. Review the diff instead of accepting a changed snapshot automatically. Record the operating system, Node version, Axios version, adapter, and test date with any approval.

The public ledger is safe to download because it contains synthetic credentials reduced to a username and password length, sanitized ephemeral ports, and no public traffic. It does not validate Databay production availability, external certificate chains, SOCKS behavior, browser Axios, redirects across real origins, or application-specific retry safety. Those boundaries need separate tests when they matter.

1. Pin and record the approved Node and Axios versions.
2. Choose one route owner: explicit proxy config, environment policy, or a reviewed custom proxy agent.
3. Keep proxy endpoint and credential fields separate; retrieve secrets at runtime.
4. Set a finite timeout, response-size limit, request-body limit, and redirect limit.
5. Add explicit AxiosError.toJSON() redaction and log only a safe error envelope.
6. Verify HTTP absolute-form and HTTPS CONNECT behavior against a controlled endpoint.
7. Prove that NO_PROXY and proxy: false select the intended direct route.
8. Classify 407 at the proxy separately from 401, 403, and 429 at the destination.
9. Bound retries to authorized idempotent operations; stop at access and quota decisions.
10. Destroy process-owned custom agents during graceful shutdown.
11. Re-run the localhost harness after a Node, Axios, agent, or proxy-policy change.
12. Verify the observed exit without treating one 200 response as proof of anonymity or future availability.

This approved guide is maintained by Robert Smith and independently reviewed by James Johnson. Re-run the evidence workflow after material Node, Axios, agent, or proxy-policy changes.