Skip to content
Troubleshooting

Troubleshooting

Step-by-step debugging for common proxy issues. Diagnose connection failures, auth errors, blocked requests, and performance problems.

Quick Debug Steps

Run these commands to isolate the issue:

Terminal
# Step 1: Test basic connectivity
curl -v -x http://basic.resi.zentislabs.com:12321 \
-U "USERNAME:YOUR_PASSWORD_country-us" \
https://httpbin.org/ip
# Step 2: Test with timeout
curl --connect-timeout 10 --max-time 30 \
-x http://basic.resi.zentislabs.com:12321 \
-U "USERNAME:YOUR_PASSWORD_country-us" \
https://httpbin.org/ip
# Step 3: Check DNS resolution
nslookup basic.resi.zentislabs.com
# Step 4: Test port connectivity
# Windows:
Test-NetConnection basic.resi.zentislabs.com -Port 12321
# Linux/macOS:
nc -zv basic.resi.zentislabs.com 12321

Python Diagnostic Script

Run this script to test your connection and identify the problem:

debug_proxy.py
import requests
import time
def debug_proxy_connection():
proxy_url = "http://USERNAME:YOUR_PASSWORD_country-us@basic.resi.zentislabs.com:12321"
proxies = {"http": proxy_url, "https": proxy_url}
print("1. Testing direct connection...")
try:
r = requests.get("https://httpbin.org/ip", timeout=10)
print(f" Direct IP: {r.json()['origin']}")
except Exception as e:
print(f" Direct failed: {e}")
print("\n2. Testing proxy connection...")
try:
start = time.time()
r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=30)
elapsed = time.time() - start
print(f" Proxy IP: {r.json()['origin']}")
print(f" Response time: {elapsed:.2f}s")
print(f" Status: {r.status_code}")
except requests.exceptions.ProxyError as e:
print(f" Proxy error: {e}")
print(" → Check credentials and proxy host/port")
except requests.exceptions.ConnectTimeout:
print(" Connection timed out")
print(" → Check firewall and network settings")
except requests.exceptions.ReadTimeout:
print(" Read timed out")
print(" → Target site may be slow, increase timeout")
except Exception as e:
print(f" Error: {e}")
debug_proxy_connection()

Connection Refused / Timeout

Symptom: Cannot connect to basic.resi.zentislabs.com:12321. Connection times out or is refused.

Possible Causes

  • Firewall blocking outbound connections on your plan's gateway port (31112 Light, 12321 Basic, 61236 Advanced)
  • Corporate proxy or VPN interfering
  • DNS resolution failure
  • ISP blocking the port

Solutions

  • Check firewall rules - allow outbound TCP on your plan's gateway port (31112 / 12321 / 61236)
  • Try connecting from a different network
  • Verify DNS: run nslookup basic.resi.zentislabs.com
  • Contact support if the issue persists

407 Proxy Authentication Required

Symptom: Proxy returns 407 status code. Requests fail with authentication error.

Possible Causes

  • Wrong proxy username or password (your API key is not a proxy credential)
  • Targeting in the wrong place: password on Light and Basic, username on Advanced
  • Credentials not sent with the request (no Proxy-Authorization)
  • Special characters in password not URL-encoded

Solutions

  • Copy the username and password from a freshly generated line (dashboard or API)
  • Check the credential format - copy a line from Dashboard → Proxies → Generate instead of building it by hand
  • URL-encode special characters in the password when you put it in a proxy URL
  • Make sure the line matches the gateway: Light 31112, Basic 12321, Advanced 61236
  • Test with cURL using the -U flag to isolate auth issues

403 Forbidden / IP Blocked

Symptom: Target website returns 403 or blocks the request. Captcha pages appear.

Possible Causes

  • Target site detecting and blocking proxy traffic
  • Too many requests from the same IP
  • Missing or suspicious User-Agent header
  • Using datacenter proxies on a site that requires residential

Solutions

  • Switch to residential or mobile proxies for sensitive targets
  • Enable rotating sessions (new IP per request)
  • Add realistic User-Agent and Accept headers
  • Reduce request rate to the target
  • Use sticky sessions for multi-step flows instead of the same IP for everything

Slow Response Times

Symptom: Requests succeed but take 5–30+ seconds. Performance is degraded.

Possible Causes

  • Target server is slow
  • Using a distant geo-target (e.g., proxy in Japan, target in US)
  • High concurrency saturating the connection

Solutions

  • Use geo-targeting to match proxy location with target server location
  • For speed-critical tasks, use datacenter or ISP proxies
  • Reduce concurrent connections
  • Set appropriate timeouts (connect: 10s, read: 30s)

502 / 503 / 504 Gateway Errors

Symptom: Proxy returns 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout.

Possible Causes

  • Target server unreachable from proxy location
  • Temporary proxy infrastructure issue
  • Connection reset by target server
  • SSL/TLS handshake failure

Solutions

  • Implement retry logic with exponential backoff
  • Try a different country or proxy type
  • Check ZentisLabs status page for outage notices
  • For persistent 502s on a specific target, contact support
  • Ensure you're not sending malformed requests through the proxy

Same IP Returned Repeatedly

Symptom: Rotating sessions return the same IP address. Expected new IP per request.

Possible Causes

  • Accidentally using a sticky line (_session-… in the password, or -session-… in the username on Advanced)
  • Connection reuse / Keep-Alive maintaining the session
  • Small proxy pool for the selected country

Solutions

  • Remove the _session-xxx part (-session-xxx on Advanced) for rotating mode - every request then gets a new IP
  • Disable HTTP Keep-Alive / connection pooling in your client
  • Try a different country with a larger IP pool

Still Need Help?

If you've tried the steps above and the issue persists, contact our support team with the following information:

  • Your account ID or username
  • The proxy type and country you're using
  • The exact error message or HTTP status code
  • Output from the diagnostic script above
  • The target URL (if relevant)
  • Timestamp of when the issue occurred

Email: support@zentislabs.com • Contact form • Discord