Integration · Node.js

Use RoProxy with Node.js

A proxy from RoProxy is a username, a password, a gateway host and an HTTP port, plus a SOCKS5 port on the Pro and Business plans. Node's built-in fetch ignores proxies unless you hand it a dispatcher, so this guide shows the setups that work today: undici's ProxyAgent for fetch, https-proxy-agent for axios, socks-proxy-agent for the SOCKS5 port, and Node's own environment-variable support. It ends with a helper that asks the RoProxy API for a new IP when a target starts answering 403 or 429.

What you need

Copy the proxy's connection string from the dashboard: it comes as GATEWAY_HOST:HTTP_PORT:USERNAME:PASSWORD. Each proxy has its own credentials, so a worker that needs its own IP needs its own proxy.

Install only what your client needs: undici for fetch, https-proxy-agent for axios, socks-proxy-agent for the SOCKS5 port.

fetch

Use undici's own fetch with a ProxyAgent: the credentials in the proxy URL become the Proxy-Authorization header. HTTPS targets go through the HTTP port with a CONNECT tunnel.

// npm install undici
import { ProxyAgent, fetch } from "undici"

const proxy = new ProxyAgent("http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT")

const res = await fetch("https://api.ipify.org?format=json", { dispatcher: proxy })
console.log(await res.json())

axios

Give axios an agent for HTTPS targets and turn off its own proxy handling, which would otherwise try to apply the proxy a second time.

// npm install axios https-proxy-agent
import axios from "axios"
import { HttpsProxyAgent } from "https-proxy-agent"

const agent = new HttpsProxyAgent("http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT")

const { data } = await axios.get("https://api.ipify.org?format=json", {
  httpsAgent: agent,
  proxy: false,
})
console.log(data)

SOCKS5

For tools that only speak SOCKS, use the SOCKS5 port of a Pro or Business proxy. It carries TCP connections only, and socks5h:// lets the proxy resolve hostnames.

// npm install socks-proxy-agent
import https from "node:https"
import { SocksProxyAgent } from "socks-proxy-agent"

const agent = new SocksProxyAgent("socks5h://USERNAME:PASSWORD@GATEWAY_HOST:SOCKS5_PORT")

https.get("https://api.ipify.org?format=json", { agent }, (res) => {
  let body = ""
  res.on("data", (chunk) => (body += chunk))
  res.on("end", () => console.log(body))
})

Rotate the IP from your code

Create an API key in the dashboard and ask for a new IP when a site starts blocking the current one. Free proxies cannot be rotated by hand: their IP changes every 10 minutes on its own. On Pro and Business a manual rotation waits 30 seconds after the previous one; calling earlier returns 429.

const API = "https://backend-api.ro-proxy.com"

async function rotate(sessionId) {
  const res = await fetch(`${API}/api/session/${sessionId}/rotate`, {
    method: "POST",
    headers: { Authorization: "Bearer API_KEY" },
  })
  if (!res.ok) throw new Error(`rotate failed: ${res.status}`)
  return (await res.json()).data.proxy_ip
}

console.log(await rotate(SESSION_ID))

Errors and retries

  • 407 Proxy Authentication Required

    The username or password is wrong, or the proxy has expired. Copy the connection string again from the dashboard.

  • ECONNRESET and timeouts

    Retry with exponential backoff; on a sticky proxy, rotate the IP after several failures in a row.

  • 429 from the rotate endpoint

    The plan's wait between manual rotations (30 seconds) has not passed yet. Wait, or switch the proxy to timed rotation.

  • 403 from the rotate endpoint

    The proxy is on the Free plan, which does not rotate by hand: its IP changes every 10 minutes on its own.

Frequently asked questions

Why not pass the proxy URL straight to fetch?

Node's built-in fetch ignores proxy settings unless you give it a dispatcher such as undici's ProxyAgent, or start Node with NODE_USE_ENV_PROXY=1 on a version that supports it.

Does HTTPS work through the HTTP port?

Yes. The client opens a CONNECT tunnel through the HTTP port, and TLS runs between your code and the website.

Can I keep the same IP across requests?

Yes. Put the proxy in sticky mode in the dashboard or with the API; the IP changes only when you rotate it, the proxy expires or the IP behind it stops working.

How do I use several IPs at once?

Use several proxies: each has its own credentials and IP, so give each worker its own ProxyAgent.

Related pages

Try it with a free proxy

Verified accounts get limited-time free proxies with random global IPs. No card needed.

Create free account