​
My request returns 407 Proxy Authentication Required

Three causes, in order of likelihood:
  1. Wrong credential format. Your username is the full keyId (starts with avp_live_ or avp_test_), and your password is the secret you copied at mint time. The wire format is HTTP Basic in Proxy-Authorization. If you put the secret as the username or vice-versa, you’ll get 407.
  2. Stale secret after rotation. If you rotated the key, the OLD secret stops working within milliseconds (we flush the gateway cache on rotate). Update your config to the new secret shown in the rotation response.
  3. Key was revoked. Check your dashboard at app.atlasvpn.live/developer — if the key is in the “Revoked” list, you’ll need to mint a new one.
Quick test: 
curl -v -x http://<keyId>:<secret>@api.atlasvpn.live:7777 https://ifconfig.me
The -v output shows the Proxy-Authorization header — make sure it’s set and the base64 decodes to <keyId>:<secret> exactly.

​
My request returns 402 Payment Required

You’ve used up your tier’s bandwidth quota for this calendar month.
  • Free tier: 500 MB/mo. The gateway returns 402 (or 429, depending on overage opt-in) once you hit the cap. Reset on the 1st of next month UTC.
  • Paid tier: Same — you hit your tier’s GB cap. Either:
    • Wait for the next billing cycle (1st UTC).
    • Enable overage in your dashboard (per-key opt-in flag, off by default — no surprise charges).
    • Upgrade tier at /developer.
To see your current usage: 
curl https://api.atlasvpn.live/api/v1/proxy/usage \
     -H "Authorization: Bearer $SUPABASE_JWT"

​
My request returns 429 Too Many Requests

You’ve exceeded your tier’s rate limit (requests per second).
TierRate limitBurst
Free3 rps30 tokens
Developer10 rps100 tokens
Team25 rps250 tokens
Scale50 rps500 tokens
Back off exponentially: wait 1s, 2s, 4s, 8s, 16s between retries. The gateway includes Retry-After in the 429 response — respect it. If you’re constantly hitting 429: you’re under-tiered. Upgrade or restructure your client to batch requests.

​
My request returns 502 Bad Gateway

The gateway accepted your CONNECT but couldn’t find a healthy node to route through. Possible causes:
  • Country pool empty. If you specified -country-XX, that country might temporarily have zero online nodes. Drop the country pin or pick a country with deeper coverage (FR/DE typically have the most nodes).
  • Node disconnected mid-tunnel. If a node’s home internet drops while serving your tunnel, the gateway returns 502. Retry the request.
  • Target host blocked. Some target ports / hosts are blocked by the protocol (SMTP-25, RFC1918 ranges). See allowed ports.
Retry strategy: exponential backoff for ≤3 retries, then surface to the user.

​
My request hangs forever

CONNECT response should arrive within 5 seconds. If it doesn’t:
  1. Check port 7777 isn’t firewalled at your end. Some corporate networks block non-standard ports.
  2. Check your DNS isn’t pointing at a stale IP. dig api.atlasvpn.live should match what you’re resolving.
  3. Try with verbose: curl -v -x http://... and watch where it stalls.
If it stalls at “trying to connect to api.atlasvpn.live”, it’s network. If it stalls at “Proxy CONNECT aborted”, it’s our gateway. If it stalls during data transfer, the node connection is bad — retry.

​
I see different IPs even though I set a sticky session

Sticky sessions only persist if:
  • The session tag is the SAME across requests.
  • Less than 10 minutes have elapsed since the last request with that tag.
  • A node matching the country (if pinned) is still online.
  • You haven’t exceeded the per-session cap (500 MB/session).
If the last node holding your sticky session went offline, the gateway re-pins to a different node and you get a new exit IP. There’s no way to guarantee the SAME exit for >10 minutes. If you need IP stability beyond sticky session limits, talk to us about a dedicated node arrangement.

​
My CONNECT to a non-standard port returns 403 Forbidden

The gateway’s port allowlist:
PortUse case
80Plaintext HTTP
443HTTPS (most common)
8080Alt-HTTP
8443Alt-HTTPS
Other ports are blocked. SMTP (25), SSH (22), database ports, and arbitrary high ports return 403 with error: port_not_allowed. This is by design — we don’t want to be a generic VPN tunnel for arbitrary protocols. If your use case genuinely needs another port, contact us with a justification.

​
I’m using HTTPS_PROXY env var but only some traffic is proxied

Different libraries respect HTTPS_PROXY / HTTP_PROXY differently:
  • curl: ✅ Respects both. Also NO_PROXY for exclusions.
  • wget: ✅ Respects both.
  • Python requests: ✅ Respects both, but must be set BEFORE the requests import in some cases.
  • Node.js: ❌ Does NOT respect env vars by default. Use https-proxy-agent library.
  • Go (net/http): ✅ Respects via http.ProxyFromEnvironment if you wire it.
  • Java HttpClient: ❌ Use -Dhttps.proxyHost= JVM args instead.
Best practice: configure the proxy explicitly per-request when you can. Env vars are convenient for shell scripts and curl one-liners but unreliable across language ecosystems.

​
My script worked yesterday but suddenly returns 407

Likely the secret was rotated. Run: 
curl https://api.atlasvpn.live/api/v1/proxy/keys \
     -H "Authorization: Bearer $SUPABASE_JWT"
Look for rotatedAt on the key. If it’s recent and you haven’t updated your config, that’s the cause. Update with the new secret (which we shown ONCE at rotation time — if you didn’t save it, you’ll need to rotate again).

​
My script is getting different IPs per request when I want stickiness

You probably forgot the -session- qualifier in the username. Sticky requires both: 
avp_live_xxx-country-fr-session-myrun42:secret
Without -session-, every request rotates. With -session-myrun42, requests with the SAME tag pin to the same exit for 10 minutes.

​
Target site blocks my requests despite using a residential IP

Some target sites use behavioural fingerprinting beyond IP. AvocadoVPN provides a clean residential IP — but if your User-Agent, TLS handshake, or browser fingerprint is bot-like, the target will still block. Mitigations:
  1. Rotate User-Agent per request — match real browser strings.
  2. Use a real browser — Puppeteer / Playwright / Selenium with stealth plugins.
  3. Slow down. Bot-detection often triggers on request frequency. DOWNLOAD_DELAY=0.5 in Scrapy, time.sleep(1) in Python — be polite.
  4. Use sticky sessions — looks more human than rotating per-request.
  5. Match the geography. US sites expect US IPs + US-locale Accept-Language. Don’t pull a French IP for a US-only product.
If a specific site blocks ALL residential proxy traffic regardless of behaviour: that’s a target-side decision we can’t help with. Bright Data, Oxylabs, AvocadoVPN — we’d all hit the same wall.

​
I exceeded my tier and got billed for overage I didn’t expect

You shouldn’t have. Overage billing is opt-in per key, and the default is OFF. To audit:
  1. Check the per-key overage flag in the dashboard.
  2. Check your usage event log via GET /api/v1/proxy/keys/<id>/events (coming Q2).
  3. If you genuinely didn’t enable overage and got billed: email support@atlasvpn.live with your account email + the time window. We’ll refund + audit.

​
I rotated my key and now nothing works

Two checks:
  1. Did you update your config? The OLD secret is dead immediately. Your env var, your CI/CD secret, your hardcoded test all need the new value.
  2. Did you save the new secret at rotation time? It’s shown ONCE in the rotate response. If you didn’t capture it, you need to rotate again and save it this time.
If you rotated and lost the secret without saving: it’s not recoverable. Rotate one more time, save the value, and update everything.

​
My node-provider client shows “online” but proxy requests through it fail

The gateway and the node-provider WebSocket connection have separate health checks. Symptoms:
  • Node-provider dashboard says “online” — the WebSocket is connected.
  • But proxy CONNECT fails with 502 — the node isn’t responding to tunnel_connect messages.
Causes:
  • Node-provider client is hung but WS keepalive still alive. Restart the client.
  • Node’s home internet has narrow upload bandwidth and is dropping tunnel data. Check your upload speed.
  • Local firewall blocking outbound to target ports. Check allowed-ports in node config.
Fix: pm2 restart atlas-node (or the equivalent on your node-provider deployment), watch the logs.

​
Anything else

Email support@atlasvpn.live with:
  • Your keyId (NEVER the secret).
  • Approximate timestamp + timezone of the failing request.
  • The full curl command (with secret REDACTED).
  • The full HTTP response including headers.
We typically reply within 12 hours during EU business hours.