> ## Documentation Index
> Fetch the complete documentation index at: https://developers.soax.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connection Debugging
> Step-by-step checklist for diagnosing SOAX proxy connection issues. Covers timeouts, auth failures, geo mismatches, and common mistakes.
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:
```bash theme={null}
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](https://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:**
```bash theme={null}
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:**
```bash theme={null}
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](https://status.soax.com) 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
Full list of every error code with causes and fixes.
Understanding detection and block rates on target websites.
Make sure your credentials and connection format are correct.
Answers to the most common questions.