> ## 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. # Error Codes & Fixes > Every error code SOAX returns, what causes it, and how to fix it. Diagnose and resolve issues without opening a support ticket. When something goes wrong with a proxy request, SOAX returns an HTTP status code along with two custom headers that tell you exactly what happened: | Header | Description | | --------------- | ------------------------------------------------ | | `X-SOAX-Error` | Machine-readable error code (e.g. `AUTH_FAILED`) | | `X-SOAX-Detail` | Human-readable explanation of what went wrong | These are SOAX-level errors. SOAX works at the transport layer, so the failures it can act on are infrastructure failures — node offline, connection refused, timeout. HTTP status codes from the target website (e.g. 403, 429, soft-block CAPTCHA pages) live inside the HTTPS tunnel and aren't visible to SOAX. See [CAPTCHA & ban rates](/troubleshooting/captcha-ban-rates) for handling those in your application. ## Validation errors (400) Your connection string was parsed but something in it wasn't valid. The request never reached node selection. ### ERR\_INVALID\_VALUE ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_INVALID_VALUE X-SOAX-Detail: Invalid value for parameter ``` **What it means:** A rule has a value that doesn't pass validation — bad country code, unknown ISP, malformed ASN, and so on. **How to fix it:** * Check the `X-SOAX-Detail` for which parameter is wrong. * Country codes are lowercase ISO 3166-1 alpha-2 (`us`, `gb`, `de`). Not uppercase, not three-letter codes. * ISP and city names use underscores for spaces (`new_york`, `verizon_wireless`). Available names are listed in your package settings. ### ERR\_MISSING\_PARAMS ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_MISSING_PARAMS X-SOAX-Detail: At least one targeting parameter is required ``` **What it means:** You didn't include any targeting rule. The auth RFCs require something in the username field. **How to fix it:** Add a targeting rule. If you don't care which country you exit from, use `country-any`. ### ERR\_UNKNOWN\_PARAM ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_UNKNOWN_PARAM X-SOAX-Detail: Unknown parameter name ``` **What it means:** A rule name in your string isn't recognised. Most common cause: a typo, or using a hyphen inside a multi-word value (so the value's tail looks like an unknown parameter name). **How to fix it:** * Check spelling against the [parameter reference](/proxies/residential#full-parameter-reference). * Make sure multi-word values use underscores: `city-los_angeles`, not `city-los-angeles`. ### ERR\_DUPLICATE\_PARAM ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_DUPLICATE_PARAM X-SOAX-Detail: Parameter specified more than once ``` **What it means:** The same rule appears twice in the connection string (e.g. `country-us-country-gb`). **How to fix it:** Remove the duplicate. Each rule appears at most once. ### ERR\_INVALID\_COMBINATION ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_INVALID_COMBINATION X-SOAX-Detail: Parameters cannot be combined ``` **What it means:** Two rules were used together that contradict each other. The most common case is `bind-node` with `rotate-timed_N`, `rotate-requests_N`, `onerror-replace`, or `prefer-lookalike` — `bind-node` is incompatible with all of those. **How to fix it:** Drop one side of the conflict. See the [`bind-node` interaction table](/proxies/residential#node-binding) for the full list. ### ERR\_PARAM\_NOT\_ALLOWED ``` HTTP/1.1 400 Bad Request X-SOAX-Error: ERR_PARAM_NOT_ALLOWED X-SOAX-Detail: Parameter not permitted on this package ``` **What it means:** A rule isn't permitted on this package or in this context — for example, a `network` value the package doesn't have enabled, or a premium feature your plan doesn't include. **How to fix it:** Remove the rule, or enable the feature in the package settings. ## Authentication errors (407) These errors mean SOAX couldn't verify your identity. Your request never reached a proxy node. ### ERR\_AUTH\_REQUIRED ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: ERR_AUTH_REQUIRED X-SOAX-Detail: No credentials supplied ``` **What it means:** No credentials were sent. Either you didn't pass a username/password, or you're trying IP Auth from an IP that isn't on the allowlist. **How to fix it:** * For username/password: make sure your client is actually sending the proxy username and password. Some HTTP clients need explicit configuration. * For IP Auth: check your outbound IP at [checker.soax.com/api/ipinfo](https://checker.soax.com/api/ipinfo) without a proxy and add it to the package's IP allowlist. ### AUTH\_FAILED ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: AUTH_FAILED X-SOAX-Detail: Invalid or missing package key ``` **What it means:** Your package key is wrong, missing, or expired. **How to fix it:** * Check that your package key matches what's in the dashboard. Copy it exactly. * Make sure the key is in the password field, not the username field. The format is `{rules}:{package_key}`, separated by a colon. * If you recently regenerated your package key, update it everywhere you use it. The old key stops working immediately. ### IP\_NOT\_ALLOWED ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: IP_NOT_ALLOWED X-SOAX-Detail: Client IP not in allowlist ``` **What it means:** You're using IP Auth, but the IP address you're connecting from isn't on the allowlist for this package. **How to fix it:** * In the dashboard, go to your proxy package settings and check the IP Allowlist. * Add the public IP of the machine making the request. This is the IP the internet sees, not your local/private IP. You can check your public IP at [checker.soax.com/api/ipinfo](https://checker.soax.com/api/ipinfo) without a proxy. * If you're behind a corporate NAT or VPN, your outbound IP may be different from what you expect. Add the correct outbound IP. * If you don't need IP Auth, switch to username/password authentication instead. ### PACKAGE\_SUSPENDED ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: PACKAGE_SUSPENDED X-SOAX-Detail: Account suspended or disabled ``` **What it means:** Your account or proxy package has been suspended. **How to fix it:** * Check the dashboard for any account notifications or alerts. * This can happen if your subscription has expired, your payment method failed, or your account was flagged for a policy violation. * Contact support if you believe this is an error. ### PACKAGE\_PAUSED ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: PACKAGE_PAUSED X-SOAX-Detail: Package is paused ``` **What it means:** The package itself has been paused from the dashboard. This is reversible — pausing keeps settings intact but rejects all requests. **How to fix it:** Resume the package from the dashboard, or use a different active package. ### PACKAGE\_NO\_CREDITS ``` HTTP/1.1 407 Proxy Authentication Required X-SOAX-Error: PACKAGE_NO_CREDITS X-SOAX-Detail: Package is out of credits or quota ``` **What it means:** Your organization's shared credit pool is empty, so there are no credits left to spend on this request. This is account-wide — it affects every package in the organization, not just this one. This is different from `429 TRAFFIC_LIMIT_EXCEEDED`, which is returned when a single package hits its own GB cap while the organization still has credits. `PACKAGE_NO_CREDITS` means the organization has run out of credits entirely. **How to fix it:** * Top up your organization's credits in the dashboard. Only organization Owners can purchase credits. * Set up auto top-up under [**Settings → Credits**](https://platform.soax.com/settings/credits) to avoid this happening again. ## Session errors (409) ### SESSION\_PARAMS\_MISMATCH ``` HTTP/1.1 409 Conflict X-SOAX-Error: SESSION_PARAMS_MISMATCH X-SOAX-Detail: Session ID reused with different rules ``` **What it means:** You sent a request with a session ID that already exists, but the rules don't match what the session was created with. Rules are locked on first use — you can't change them by sending different rules on a later request. **How to fix it:** * Use a new session ID if you want different rules. * Keep the rules identical every time you send the same session ID. ## Rate and quota errors (429) These errors mean your request was valid but exceeded a limit on your package. ### RATE\_LIMIT\_EXCEEDED ``` HTTP/1.1 429 Too Many Requests X-SOAX-Error: RATE_LIMIT_EXCEEDED X-SOAX-Detail: RPS or concurrent connection limit reached ``` **What it means:** You've hit the requests-per-second (RPS) or concurrent connection limit on your package. **How to fix it:** * Reduce the number of parallel requests you're sending. * If you're using a worker pool, lower the concurrency. * Check your package limits in the dashboard. Higher-tier plans have higher RPS and connection limits. * If you consistently need more throughput, consider upgrading your plan. ### TRAFFIC\_LIMIT\_EXCEEDED ``` HTTP/1.1 429 Too Many Requests X-SOAX-Error: TRAFFIC_LIMIT_EXCEEDED X-SOAX-Detail: Traffic limit exceeded ``` **What it means:** This package has a per-package traffic limit (in GB) and you've used it all. The cap is set by an organization Owner and applies only to this package — your organization may still have plenty of credits; this package just isn't allowed to consume more. This is different from `407 PACKAGE_NO_CREDITS`, which means the organization's entire credit pool is empty. `TRAFFIC_LIMIT_EXCEEDED` is a cap on one package, not an account-wide credit shortage. **How to fix it:** * Check this package's usage in the dashboard under [Usage & Analytics](https://platform.soax.com/usage). * Ask an organization Owner to raise or remove the package's traffic limit. * If you also see `407 PACKAGE_NO_CREDITS`, the organization is out of credits — top up to continue. ## Node errors (502) These errors mean SOAX accepted your request but couldn't complete it through the proxy network. ### NODE\_UNAVAILABLE ``` HTTP/1.1 502 Bad Gateway X-SOAX-Error: NODE_UNAVAILABLE X-SOAX-Detail: Node went offline or connection refused ``` **What it means:** The node assigned to your request went offline or refused the connection. **How to fix it:** * If you're using rotating mode (no session), just retry. The next request will get a different node. * If you're using a session, your `onerror` rule controls what happens next. The default (`onerror-replace`) automatically gets a new node. If you set `onerror-fail`, you'll see this error instead of an automatic replacement. * If this happens frequently for a specific geo target, the available pool in that region may be limited. Try broadening your filters (e.g. target the country instead of a specific city). ### NODE\_NOT\_FOUND ``` HTTP/1.1 502 Bad Gateway X-SOAX-Error: NODE_NOT_FOUND X-SOAX-Detail: No nodes matching country=us, city=los_angeles, network=mob ``` **What it means:** No nodes in the pool match your filtering rules right now. **How to fix it:** * Check the `X-SOAX-Detail` header for exactly which filters couldn't be matched. * Broaden your targeting. The most common cause is combining a small city with a specific ISP or carrier, leaving very few eligible nodes. * If you're targeting mobile (`network-mob`), remember the mobile pool is smaller than residential. Try `network-res` or `network-any` to see if the issue is mobile-specific. * Some country/city/ISP combinations may have limited availability at certain times of day. Try again later or target a nearby city instead. ### RETRIES\_EXHAUSTED ``` HTTP/1.1 502 Bad Gateway X-SOAX-Error: RETRIES_EXHAUSTED X-SOAX-Detail: All onerror-retry_N attempts failed, replacement also failed ``` **What it means:** All retries failed and the replacement node also failed. With `onerror-retry_N`, SOAX retries on the current node up to N times. If all of those fail, it then tries to replace the node — and that replacement attempt also failed. **How to fix it:** * This usually means the pool matching your filters is under heavy load or very small. Broaden your geo or ISP filters. * If you're using `onerror-retry_N` with a high retry count, consider reducing it. Retrying many times on a failing node wastes time. * Check if the issue is transient by retrying the request after a short delay. ## Binding errors (503) ### BOUND\_NODE\_FAILED ``` HTTP/1.1 503 Service Unavailable X-SOAX-Error: BOUND_NODE_FAILED X-SOAX-Detail: bind-node session and node has failed, no replacement allowed ``` **What it means:** You used `bind-node` to lock your session to a specific node, and that node is no longer available. Because `bind-node` prevents automatic replacement, the request fails. **How to fix it:** * This is expected behavior with `bind-node`. The tradeoff for strict node binding is that you lose the safety net of automatic replacement. * Start a new session (use a different session ID) to get assigned to a new node. * If you want retries on the same node before failing, combine `bind-node` with `onerror-retry_N`. For example: `session-x-bind-node-onerror-retry_3`. * If you don't need strict node binding, remove `bind-node` from your rules and let the system handle replacement automatically. ## Protocol errors (403) ### DISALLOWED ``` HTTP/1.1 403 Forbidden X-SOAX-Error: DISALLOWED X-SOAX-Detail: Protocol not in allowed list ``` **What it means:** The protocol you used isn't permitted on this package. **How to fix it:** * Switch to an allowed protocol (HTTP, HTTPS, or SOCKS5). * If you need a specific protocol that's currently blocked, update the package settings in the dashboard. ## Timeout errors (504) ### GATEWAY\_TIMEOUT ``` HTTP/1.1 504 Gateway Timeout X-SOAX-Error: GATEWAY_TIMEOUT X-SOAX-Detail: Request timed out after tunnel established ``` **What it means:** The proxy connection was established successfully, but the request to the target website timed out. This could be the node being slow or the target website being unresponsive. **How to fix it:** * Check if the target website is accessible directly (without a proxy). If it's down, the proxy can't help. * If the target is a large page or slow API, increase the timeout on your HTTP client. * Try a different geo target. Some regions have higher latency nodes than others. * If this happens consistently on specific targets, the target may be rate-limiting or blocking the exit IP at the TCP level. Try rotating to a fresh IP. ## Quick reference | Code | X-SOAX-Error | Category | Cause | | ---- | ------------------------- | ---------- | ---------------------------------------------------- | | 400 | `ERR_INVALID_VALUE` | Validation | Bad value for a rule (country code, ISP, ASN, etc.) | | 400 | `ERR_MISSING_PARAMS` | Validation | No targeting rule supplied | | 400 | `ERR_UNKNOWN_PARAM` | Validation | Unrecognised rule name | | 400 | `ERR_DUPLICATE_PARAM` | Validation | Same rule appears twice | | 400 | `ERR_INVALID_COMBINATION` | Validation | Rules that can't be used together | | 400 | `ERR_PARAM_NOT_ALLOWED` | Validation | Rule not permitted on this package or context | | 403 | `DISALLOWED` | Protocol | Protocol not in the allowed list | | 407 | `ERR_AUTH_REQUIRED` | Auth | No credentials supplied | | 407 | `AUTH_FAILED` | Auth | Wrong or missing package key | | 407 | `IP_NOT_ALLOWED` | Auth | Client IP not on allowlist | | 407 | `PACKAGE_SUSPENDED` | Account | Account suspended | | 407 | `PACKAGE_PAUSED` | Account | Package paused | | 407 | `PACKAGE_NO_CREDITS` | Account | Organization credit pool empty (account-wide) | | 409 | `SESSION_PARAMS_MISMATCH` | Session | Session ID reused with different rules | | 429 | `RATE_LIMIT_EXCEEDED` | Limit | RPS or connection limit hit | | 429 | `TRAFFIC_LIMIT_EXCEEDED` | Limit | Package's own GB cap reached (org still has credits) | | 502 | `NODE_UNAVAILABLE` | Node | Node went offline | | 502 | `NODE_NOT_FOUND` | Node | No nodes match your filters | | 502 | `RETRIES_EXHAUSTED` | Node | All retries and replacement failed | | 503 | `BOUND_NODE_FAILED` | Binding | Bound node failed, no replacement allowed | | 504 | `GATEWAY_TIMEOUT` | Timeout | Request timed out after tunnel established | ## Still stuck? If you've worked through the fixes above and the issue persists, check the [Connection Debugging](/troubleshooting/connection-debugging) page for a step-by-step diagnostic checklist, or contact support through the dashboard. ## Next steps Step-by-step checklist for diagnosing connection issues. Answers to the most common questions. Full rule reference including error handling options. Make sure your credentials are set up correctly.