Error Codes & Fixes

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 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.
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 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 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 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 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.
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 page for a step-by-step diagnostic checklist, or contact support through the dashboard.

Next steps

Connection debugging

Step-by-step checklist for diagnosing connection issues.

FAQ

Answers to the most common questions.

Residential proxies

Full rule reference including error handling options.

Authentication

Make sure your credentials are set up correctly.

​Validation errors (400)

​ERR_INVALID_VALUE

​ERR_MISSING_PARAMS

​ERR_UNKNOWN_PARAM

​ERR_DUPLICATE_PARAM

​ERR_INVALID_COMBINATION

​ERR_PARAM_NOT_ALLOWED

​Authentication errors (407)

​ERR_AUTH_REQUIRED

​AUTH_FAILED

​IP_NOT_ALLOWED

​PACKAGE_SUSPENDED

​PACKAGE_PAUSED

​PACKAGE_NO_CREDITS

​Session errors (409)

​SESSION_PARAMS_MISMATCH

​Rate and quota errors (429)

​RATE_LIMIT_EXCEEDED

​TRAFFIC_LIMIT_EXCEEDED

​Node errors (502)

​NODE_UNAVAILABLE

​NODE_NOT_FOUND

​RETRIES_EXHAUSTED

​Binding errors (503)

​BOUND_NODE_FAILED

​Protocol errors (403)

​DISALLOWED

​Timeout errors (504)

​GATEWAY_TIMEOUT

​Quick reference

​Still stuck?

​Next steps