QuotaGuard and Netlify Integration Guide
QuotaGuard gives each subscription two load-balanced static outbound IPv4 addresses. Route the HTTPS calls from your Netlify Node.js Functions through an Undici ProxyAgent, then allowlist both addresses shown in your QuotaGuard dashboard.
This guide covers Netlify Functions running Node.js 24. Native Node.js fetch uses Undici and takes a dispatcher option. Passing agent: new HttpsProxyAgent(...) does not configure native fetch and can silently send the request directly.
Two ways to use this guide: Setting it up yourself? Start with the Guided setup (Quickstart). Working with an AI coding agent? Share the page and use the in-depth programmatic reference to configure the integration, verify the connection and troubleshoot.
To let your agent set up and test the connection, provide the required proxy connection details through its secure credential mechanism rather than sharing your QuotaGuard account password. Review any changes it proposes.
Why Netlify Functions Need Static IPs
Netlify’s default outbound addresses can change as its infrastructure scales. A destination that restricts requests by source IP needs a stable egress path. This applies to the destination’s specific API and security policy; a successful HTTP response alone does not prove which route was used.
The path configured here is:
Netlify Node.js Function -> QuotaGuard proxy -> HTTPS destination
Only calls using the configured client follow this path. Setting QUOTAGUARDSTATIC_URL alone does not change routing for native fetch, other libraries, or vendor SDKs.
Native Private Connectivity vs QuotaGuard
Netlify Private Connectivity is an Enterprise add-on requiring High-Performance Edge or High-Performance Build. It supplies static addresses for builds and serverless functions. Function support is limited to cmh (Ohio), fra (Frankfurt), and lhr (London), and does not include Edge Functions. Allowlist all addresses Netlify supplies for your chosen regions when using that feature.
QuotaGuard supplies a pair of static IPs per subscription for requests explicitly routed through its proxy. Choose between the native feature and a proxy according to your plan, function region, and the clients you need to route. This guide does not establish QuotaGuard proxy support in Netlify Edge Functions.
Guided setup (Quickstart)
Follow the connection, function configuration and verification steps below. Both native-fetch and Axios examples are included. If a check fails, use Troubleshooting.
1. Getting Started
Find your proxy URL and two static IPs in your QuotaGuard dashboard. Choose a proxy region near your function and destination. Check the function region under Cloud compute > Functions > Region rather than assuming it is Virginia. New Netlify sites default to Ohio (cmh); older sites can differ. See Netlify function configuration.
For QuotaGuard Static, the URL has this shape:
http://username:password@<your-quotaguard-proxy-host>:9293
Use the exact QUOTAGUARDSTATIC_URL value from your dashboard. Allowlist both dashboard IPs at the destination. Do not obtain allowlist addresses by resolving the proxy hostname.
2. Configuring Netlify Functions (Node.js)
Step 1: Set the Runtime and Environment Variables
Use Node.js 24 locally and select nodejs24.x through Netlify’s AWS_LAMBDA_JS_RUNTIME environment variable in the UI, CLI, or API. Netlify manages the deployed patch version, which can differ from your local version.
In Netlify’s environment variable settings, add:
| Variable | Value |
|---|---|
QUOTAGUARDSTATIC_URL |
Exact Static HTTP proxy URL from your dashboard |
QUOTAGUARD_EXPECTED_IPS |
Both dashboard IPv4 addresses, separated by a comma; used by the verification function below |
Where scope selection is available, include Functions. Select the intended deploy context. These are server-side values; keep the credential-bearing proxy URL out of browser code and logs. Values declared in netlify.toml are not available as function runtime variables. Updated values require a new deploy. See Netlify function environment variables.
Step 2: Install a Compatible Undici Version
npm install --save-exact undici@7.30.1
Keep package.json and the generated lockfile with your application. This guide’s native-fetch path was tested locally on Node.js 24.14.1, with bundled Undici 7.24.4 and npm Undici 7.30.1, on Linux x86-64.
The version matters: npm Undici 8.12.3 failed with this Node runtime’s native fetch (UND_ERR_INVALID_ARG, invalid onRequestStart method). Do not substitute a new major version without testing that runtime and dispatcher together.
Step 3: Add a Shared Request Helper
Create netlify/lib/quotaguard.mjs, outside the functions entry directory:
// netlify/lib/quotaguard.mjs
import { ProxyAgent } from 'undici';
export async function proxyJson(url, options = {}) {
const proxyUrl = process.env.QUOTAGUARDSTATIC_URL;
if (!proxyUrl) throw new Error('Proxy configuration missing');
const parsed = new URL(proxyUrl);
if (!['http:', 'https:'].includes(parsed.protocol)) {
throw new Error('Use an HTTP or HTTPS proxy URL');
}
const dispatcher = new ProxyAgent(proxyUrl);
try {
const response = await fetch(url, {
...options,
dispatcher,
signal: options.signal ?? AbortSignal.timeout(10_000),
redirect: 'error'
});
if (!response.ok) {
await response.body?.cancel();
throw new Error(`Upstream HTTP ${response.status}`);
}
return await response.json();
} finally {
await dispatcher.close();
}
}
This helper reads JSON, checks HTTP status, bounds each call, and closes its dispatcher after consuming or cancelling the body. It creates one dispatcher per helper call for straightforward cleanup. A pooled application can instead reuse a module-scoped dispatcher, but must manage its lifecycle and keep passing it to each relevant call. Do not close a shared dispatcher while other requests use it.
The default timeout is a request budget, not a change to Netlify’s function duration. Redirects are rejected so this example does not forward an operation to an unexpected destination. Replace example destinations below with fixed, trusted HTTPS endpoints and their required authentication. Add your application’s own caller authentication and input validation before exposing these functions.
Node.js documents the custom dispatcher option. The Undici 7 ProxyAgent API documents proxy routing and credentials. HttpsProxyAgent is an http.Agent for compatible clients; it is not a native-fetch dispatcher.
Basic GET Request
// netlify/functions/api-call.mjs
import { proxyJson } from '../lib/quotaguard.mjs';
export default async () => {
try {
const data = await proxyJson('https://api.example.com/data');
return Response.json(data);
} catch {
return Response.json({ error: 'Outbound request failed' }, { status: 502 });
}
};
POST Request with JSON Body
This is a generic JSON example, not a payment or transaction implementation. Test against a controlled endpoint first. It does not automatically retry writes.
// netlify/functions/submit-data.mjs
import { proxyJson } from '../lib/quotaguard.mjs';
export default async (req) => {
if (req.method !== 'POST') {
return new Response('Method not allowed', {
status: 405, headers: { Allow: 'POST' }
});
}
let payload;
try {
payload = await req.json();
} catch {
return Response.json({ error: 'Invalid JSON' }, { status: 400 });
}
try {
const result = await proxyJson('https://api.example.com/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
});
return Response.json(result);
} catch {
return Response.json({ error: 'Outbound request failed' }, { status: 502 });
}
};
Error Handling and Background Functions
Native fetch resolves normally for destination HTTP errors, so check response.ok. Connection failures, TLS failures, timeouts, and failed proxy CONNECT requests can reject the promise instead. The helper covers both paths and the handlers return a generic error without exposing credentials, raw errors, or upstream response bodies.
A proxy’s CONNECT rejection may surface only as TypeError: fetch failed. Do not classify proxy authentication by searching error.message for 407. Use protected server-side diagnostics and proxy logs, with secrets removed, to distinguish proxy authentication from destination authentication or transport failures.
Background functions use the same dispatcher approach. Netlify supports up to 15 minutes and can retry failed invocations; its initial HTTP 202 acknowledges invocation, not successful delivery. Use idempotency controls for repeatable work and check each outbound result. See Netlify background functions.
Using Axios Instead of Fetch
Axios uses a different configuration. For an HTTPS target, use httpsAgent and proxy: false so Axios does not apply a separate proxy configuration. The local routing comparison used Axios 1.20.0 and https-proxy-agent 9.1.0.
npm install --save-exact axios@1.20.0 https-proxy-agent@9.1.0
// netlify/functions/axios-example.mjs
import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
export default async () => {
const proxyUrl = process.env.QUOTAGUARDSTATIC_URL;
if (!proxyUrl) {
return Response.json({ error: 'Proxy configuration missing' }, { status: 500 });
}
let agent;
try {
agent = new HttpsProxyAgent(proxyUrl);
const response = await axios.get('https://api.example.com/data', {
httpsAgent: agent,
proxy: false,
timeout: 10_000,
maxRedirects: 0
});
return Response.json(response.data);
} catch {
return Response.json({ error: 'Outbound request failed' }, { status: 502 });
} finally {
agent?.destroy();
}
};
The Axios example and native-fetch helper do not configure SDKs that use another HTTP client. Verify each client’s egress independently.
3. Testing Your Implementation
Local Testing with Netlify Dev
Run netlify dev in your application’s existing development environment with the required local variables set securely. Invoke the function through the local URL reported by the CLI. Use a controlled target for JSON POST tests.
Netlify Dev runs on your machine. A local success does not prove routing from a hosted function. For each environment, verify the IP through the same client configuration used by the real API call.
Test Function to Verify Proxy
This diagnostic checks the returned address against both configured dashboard IPs. It does not infer proxy success from HTTP 200 alone.
// netlify/functions/test-proxy.mjs
import { isIP } from 'node:net';
import { proxyJson } from '../lib/quotaguard.mjs';
export default async () => {
const expected = (process.env.QUOTAGUARD_EXPECTED_IPS ?? '')
.split(',').map(ip => ip.trim()).filter(Boolean);
if (expected.length !== 2 || new Set(expected).size !== 2 ||
!expected.every(ip => isIP(ip) === 4)) {
return Response.json({ error: 'Configure both dashboard IPv4 addresses' }, { status: 500 });
}
try {
const data = await proxyJson('https://ip.quotaguard.com');
const matches = typeof data.ip === 'string' && expected.includes(data.ip);
return Response.json({
your_static_ip: data.ip,
proxy_working: matches
}, { status: matches ? 200 : 502 });
} catch {
return Response.json({ error: 'Proxy verification failed', proxy_working: false }, { status: 502 });
}
};
Expected response, with a member of your actual dashboard pair:
{
"your_static_ip": "<one of the two dashboard IPv4 addresses>",
"proxy_working": true
}
The IP endpoint returns JSON of the form {"ip":"..."}. Seeing the same valid address repeatedly is normal: assignment is per connection, and DNS caching or a reused connection can keep a client on one node. Repeated requests do not guarantee that both addresses will appear. Allowlist both regardless.
Protect or remove diagnostic endpoints after use. An IP match checks this request’s observed egress. Cross-check the proxy’s Log Viewer and verify the real API call’s client as well.
Programmatic reference
The shared implementation above contains the connection URL and allowlist, runtime, secrets and deploy requirements, Undici version requirements, request helper and GET/POST examples, Axios alternative, and verification function and expected response. Use those sections together with the runtime limitations, protocol distinctions and troubleshooting below.
Configuring Netlify Edge Functions (Deno)
The Node.js ProxyAgent setup above does not apply to Netlify Edge Functions. A Deno API’s availability outside Netlify does not establish support in Netlify’s hosted Edge runtime. For this implementation, put the outbound call in a Node.js Function; if an Edge Function calls it, secure that internal application route as well.
Database Connections
The examples here cover HTTPS requests. A database HTTP API can use this pattern only if its actual HTTP client accepts the dispatcher and its destination supports that API. Native database protocols and WebSocket transports need their own supported proxy configuration; a dispatcher passed to fetch does not configure them. Function lifetime alone does not establish whether a particular driver supports SOCKS or a tunnel.
Latency Considerations
The proxy adds a network hop. Measure latency from your function region to the target rather than assuming a fixed overhead. Route only calls requiring the static source IP, while configuring every relevant authentication and resource call made by that integration. A vendor SDK may make additional calls through its own client.
Troubleshooting
| Symptom | What to check |
|---|---|
| HTTP 200, but the wrong IP | Native fetch needs dispatcher, not agent. Require dashboard IP membership. Check the deployed code, client, deploy context, and proxy logs. |
| Only one dashboard IP appears | This is valid. Connections can stay on one address; both IPs must remain allowlisted. |
fetch failed with a proxy CONNECT rejection |
Check the dashboard proxy URL, URL-encoded credentials, product scheme and port, and proxy logs. A CONNECT 407 may not appear in the top-level error message. Never print the credential URL. |
| Destination HTTP 401 or 403 | Check destination credentials, permissions, and source-IP rules separately. The helper rejects non-2xx responses; a 403 alone does not establish an IP rejection. |
| Timeout or connection refusal | Confirm the exact dashboard host and port, target reachability, and request budget. Do not retry directly if the proxy fails. Netlify function limits and HTTP request timeouts are separate. |
| TLS certificate failure | Check the host, trust chain, and system clock. Keep TLS verification enabled; do not use NODE_TLS_REJECT_UNAUTHORIZED=0. |
UND_ERR_INVALID_ARG / invalid onRequestStart method |
Check Node and npm Undici versions. The tested native-fetch combination uses Undici 7.30.1; Undici 8.12.3 was incompatible with native fetch on Node 24.14.1. |
| Module not found | Install undici as a production dependency, include the lockfile, and confirm the helper’s import path is included in the function bundle. |
| Variable missing | Use Netlify UI, CLI, or API; include Functions scope where available, select the right context, and create a new deploy after changes. Do not rely on netlify.toml runtime variables. |
| Invalid upstream JSON | Confirm the endpoint returns JSON. A proxy connection does not guarantee the destination’s response format. |
| Netlify Edge or an SDK still bypasses | The Node-fetch dispatcher does not configure Edge runtimes or other clients. Use the tested Node Function path and verify each client independently. |
The helper uses a ten-second per-call budget. Netlify currently documents a 60-second synchronous execution limit and a 15-minute background limit, with different limits for other function types. Consult function configuration; adding an arbitrary timeout value to netlify.toml does not extend those fixed limits.
Common Use Cases
Use the GET pattern for partner API reads and the POST pattern for a controlled JSON endpoint. For webhook delivery, compute the signature over the exact bytes sent and apply the destination’s retry and idempotency policy. Financial APIs need their own reviewed authentication, authorization, and transaction controls; the generic POST example does not implement those controls.
QuotaGuard Static vs QuotaGuard Shield
| Feature | QuotaGuard Static | QuotaGuard Shield |
|---|---|---|
| Proxy URL | Dashboard http:// URL, port 9293 |
Dashboard https:// URL, port 9294 |
| Customer-to-proxy hop | Plaintext | TLS-encrypted |
| HTTPS payload | Tunneled end-to-end, never decrypted at the proxy | Tunneled end-to-end, never decrypted at the proxy |
| Best for | Most apps | Regulated data or environments requiring TLS on every hop |
| Starting direct price | $19/month | $29/month |
Static is appropriate for most apps. Choose Shield when the workload handles regulated data or requires TLS between the app and the proxy. For Shield, supply the dashboard HTTPS proxy URL on port 9294 to ProxyAgent; do not combine Shield’s port with Static’s http:// scheme.