Troubleshooting flow

Find the section matching your symptom and work down in order. Each step is independently verifiable — don't skip ahead, because skipping usually means changing three things and not knowing which one helped.

Universal first step: minimal reproduction

Whatever the symptom, establish a baseline with the shortest possible curl command. This alone eliminates half of all problems (client library configuration, connection pooling, application logic).

# 1. No options at all
curl -v -x 'http://USERNAME:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org

# 2. Once that works, add a country
curl -v -x 'http://USERNAME-country-US:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org

# 3. Once that works, add everything you actually use
curl -v -x 'http://USERNAME-country-US-state-California-city-Los%20Angeles-session-t1-time-30:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org

Can't connect at all

Getting 407

Read X-NextProxy-Error first: proxy_auth_required means missing or unparseable authentication; invalid_credentials means the username or password does not match. For the latter, copy the original console text and check case plus I, l and 1; do not reconstruct credentials from screenshots.

curl -v -x 'http://USERNAME:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org 2>&1 | grep -i proxy-auth

# Dangerous
curl -x "http://user:p@ss!word@host:58971" ...

# Safe
curl -x 'http://user:p@ss!word@host:58971' ...

Getting 400

invalid_proxy_parameters means invalid username option syntax, order, range or dependency. Test the base username without options, then add them one at a time; check the username option reference. For invalid_request, inspect the request and destination format.

Getting 403

Use X-NextProxy-Error to separate the causes:

• account_disabled / account_expired: check account status and expiry in the console.
• access_denied: check account permissions, source bindings and port authentication mode; passwordless ports must not receive username/password credentials.
• target_denied: test an allowed public destination and check target restrictions.

A destination 403 after 200 Connection Established belongs to the website and does not indicate an incorrect proxy password.

Getting 402

For traffic_exhausted, check the shared user traffic pool; for account_quota_exhausted, check the sub-account cap minus usage; for quota_exhausted, check available quota. A positive pool balance does not guarantee admission when a sub-account cap is exhausted. Reconnecting cannot restore quota. See proxy sub-accounts.

Getting 429

connection_limit means account concurrency or connection rate reached the limit. Reduce concurrency, reuse connections where suitable and back off instead of reconnecting in a burst. Source-IP/global protection before protocol detection may close TCP directly; see limits and quotas.

Getting 502, 503 or 504

• 502 upstream_connection_failed: exit connection or handshake failed.
• 503 service_unavailable: no matching proxy IP or a service is temporarily unavailable.
• 504 upstream_timeout: proxy connection establishment timed out.

For 503, remove city, state and country one at a time and copy exact geographic values from the console catalogue. See geographic targeting. If a sticky session is unavailable, choose a new session value to start a new session; the new session may use a different exit IP.

For requests safe to replay, retry up to three times with backoff. If failures persist, provide the time, gateway, machine code and redacted logs for operator diagnosis. Authentication or policy errors during exit connection establishment return gateway 502; they do not require changing otherwise correct proxy credentials.

The connection drops with no response at all

This happens before protocol detection, too early to build an HTTP response:

• Global connection count or per-source-IP concurrency at its ceiling
• New connection rate exceeded (1,000/s per IP)
• More than 5 seconds waiting for the first byte
• Gateway resources at the high-water mark

What to do: reduce concurrency and connection establishment rate. Note that under resource pressure only new connections are refused while existing ones continue normally — which is exactly why "old jobs are fine, new jobs can't connect".

Wrong exit IP

The IP didn't change at all (same as direct)

echo "direct: $(curl -s https://api.ipify.org)"
echo "proxy:  $(curl -sS -x 'http://USER-country-US:PASS@GATEWAY_HOST:58971' https://api.ipify.org)"

Identical values mean the proxy was never used:

The location isn't the country I asked for

curl -sS -x 'http://USER-country-DE:PASS@GATEWAY_HOST:58971' https://ipinfo.io/json

If country isn't DE:

1. Confirm the value is two uppercase letters — de is rejected (400 invalid_proxy_parameters), not normalised to DE
2. If you get a 200 with the wrong country, cross-check against another geolocation database — they genuinely disagree

The city doesn't match

An IP that should be fixed keeps changing

An IP that should change doesn't

# Each curl invocation is a new process and connection, so this rotates
for _ in 1 2 3; do
  curl -sS -x 'http://USER-country-US:PASS@GATEWAY_HOST:58971' https://api.ipify.org; echo
done

If curl rotates but your code doesn't, the connection is almost certainly being reused. Rotation needs two things:

1. No session option
2. A new connection

The second is the one people miss. Per-language approaches are in Sticky sessions and rotation.

Slow

First, identify which leg is slow

curl -s -o /dev/null \
  -x 'http://USER-country-US:PASS@GATEWAY_HOST:58971' \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  https://example.com

Throughput won't come up

curl -H 'Accept-Encoding: gzip, deflate, br' ...

Connections dropping mid-stream

Detected or blocked by the target site

This class of problem isn't on the gateway side, but it comes up often enough to warrant a diagnostic path.

Still stuck

Open a ticket (POST /api/v1/support/tickets) with:

• The complete curl -v output (credentials redacted)
• The full username options you used (base username redacted)
• The gateway node address and port
• The exact status code or SOCKS5 reply code received
• The time range of the failures, with timezone
• The failure rate: 100% or intermittent
• What you've already ruled out