Skip to main content
If your proxy requests aren’t working, work through this checklist before contacting support. Most issues fall into a few common categories, and you can usually fix them yourself in a few minutes.

​
Step 1: Check your authentication

The most common reason requests fail is an authentication problem. Run this test command from your terminal: 
curl -x proxy.soax.com:1337 -U "country-any:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
If you get a 407 AUTH_FAILED response:
  • Make sure your package key matches what’s shown in the dashboard under Quick Connect. Copy it exactly.
  • Check that the key is in the password position, after the colon. The format is {rules}:{package_key}. A common mistake is putting the key in the wrong field.
  • If you recently regenerated your key, the old one stops working immediately. Update it everywhere.
If you get a 407 IP_NOT_ALLOWED response:
  • You’re using IP Auth, but your current IP isn’t on the allowlist.
  • Visit checker.soax.com/api/ipinfo directly (without a proxy) to see your public IP, then add it to the allowlist in the dashboard.
  • If you’re behind a VPN, corporate NAT, or cloud instance, your outbound IP may not be what you expect.
If you get a 407 PACKAGE_SUSPENDED response:
  • Your account or package has been suspended. Check the dashboard for notifications, or contact support.
If the test command above returns a valid JSON response with an IP, your authentication is working. Move to the next step.

​
Step 2: Check your connection string format

SOAX connection strings use hyphens to separate rules and underscores within multi-word values. Getting this wrong is a common source of silent failures or unexpected behavior. Correct: 
country-us-city-los_angeles-session-job1:YOUR_PACKAGE_KEY@proxy.soax.com:1337
Wrong (hyphen in city name instead of underscore): 
country-us-city-los-angeles-session-job1:YOUR_PACKAGE_KEY@proxy.soax.com:1337
The second example parses los as the city and angeles as an unknown parameter. You won’t get an error, but the targeting will be wrong. Common formatting mistakes:
  • Using hyphens inside values (los-angeles instead of los_angeles)
  • Missing the colon between rules and package key
  • Putting the package key in the username field instead of the password field
  • Using = instead of - to set values (country=us instead of country-us)
  • Forgetting country-any when you don’t want geo-targeting (at least one targeting rule is required)

​
Step 3: Check your geo-targeting

If your requests succeed but return IPs from the wrong country or city, the issue is usually in your targeting parameters. Run a targeted request and check the response: 
curl -x proxy.soax.com:1337 -U "country-de-city-berlin:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
Check the country_code and city fields in the response. If they don’t match what you targeted:
  • Make sure the country code is lowercase ISO 3166-1 alpha-2 (e.g. us, gb, de). Common pitfalls: uppercase (US), using uk instead of the correct code gb, or three-letter codes like GER.
  • Check for typos in region and city names. Use underscores for spaces.
  • If you’re targeting a very specific location (small city + ISP), the pool may be too small and the system can’t find a match. The X-SOAX-Detail header will tell you if this is the case. Try removing the most specific filter first (city or ISP) and see if the country matches.
If you get a 502 NODE_NOT_FOUND response:
  • No nodes match your filter combination. Broaden your targeting.
  • Mobile pools are smaller than residential. If you’re using network-mob, try network-res to see if the issue is mobile-specific.
  • Some regions have limited coverage at certain times of day. Try again later.

​
Step 4: Check for timeouts

If your requests hang and eventually time out, the issue could be on the proxy side, the target side, or your client configuration. Test with a known-good target first: 
curl -x proxy.soax.com:1337 -U "country-us:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
If this works but your actual target times out, the problem is between the proxy node and the target website, not with SOAX itself. If the checker also times out:
  • Check that you can reach proxy.soax.com on port 1337 from your network. Some corporate firewalls block non-standard ports.
  • Try from a different network (e.g. phone hotspot) to rule out local network issues.
  • Check the SOAX status page for any ongoing incidents.
If only your target times out:
  • The target website may be slow or rate-limiting the exit IP. Try a different country or session to get a fresh IP.
  • If you get 504 GATEWAY_TIMEOUT, the proxy connection was established but the target didn’t respond in time. Increase the timeout on your HTTP client.
  • Some targets block traffic at the TCP level without sending a response. This looks like a timeout from your side. Try rotating to a new IP.

​
Step 5: Check your session behavior

If your session isn’t holding the same IP across requests, or if sessions are breaking unexpectedly: Ephemeral sessions expire after 60 seconds of inactivity. If there’s a gap of more than 60 seconds between requests with the same session ID, the session is gone. The next request creates a new session and gets a new node. If your workflow has natural pauses longer than that, build in keepalive requests to hold the session open. Conflicting rules on the same session ID return 409 SESSION_PARAMS_MISMATCH. If you send country-us-session-job1 and then country-gb-session-job1, the second request fails because the session was created with US targeting and you’re trying to change it. To change rules, use a new session ID. Rotation rules force IP changes within a session. If you set rotate-timed_300 and your IP changes after 300 seconds, that’s working as intended. Remove the rotation rule if you want to keep the same IP for the full session lifetime.

​
Step 6: Check your package limits

If requests were working and suddenly stopped: Credit exhaustion. If your organization’s credits are used up, requests will be blocked. Check your balance in the dashboard under Usage & Analytics. Traffic limit on the package. If the organization owner set a traffic limit on your proxy package, you’ll get 429 TRAFFIC_LIMIT_EXCEEDED when you hit it. Ask the owner to increase or remove the limit. RPS or connection limit. If you’re sending too many requests in parallel, you’ll get 429 RATE_LIMIT_EXCEEDED. Reduce your concurrency or upgrade your plan for higher limits.

​
Quick diagnostic checklist

Work through this in order. Stop as soon as you find the issue.
  1. Can you reach the checker with country-any? If no, it’s an auth or network problem (steps 1 and 4).
  2. Does the checker return the right country? If no, it’s a targeting problem (step 3).
  3. Does your actual target work? If no, it’s a target-side or timeout problem (step 4).
  4. Does your session hold the same IP? If no, check session behavior (step 5).
  5. Are you getting 429 errors? Check your limits (step 6).
  6. Still not working? Contact support through the dashboard with your X-SOAX-Error code and the connection string you’re using (with the package key redacted).
When contacting support, include the X-SOAX-Error and X-SOAX-Detail header values from the failed response. These give the support team the fastest path to diagnosing your issue.

​
Next steps

Error codes

Full list of every error code with causes and fixes.

CAPTCHA & ban rates

Understanding detection and block rates on target websites.

Authentication

Make sure your credentials and connection format are correct.

FAQ

Answers to the most common questions.