Routing and failure behavior

Routing selects one eligible upstream path for a proxy connection. It is deterministic where session continuity requires it, capability-aware where providers differ, and intentionally conservative when a request cannot be satisfied.

Selection order

1. Authenticate the proxy username and password, then resolve the active user, package, order, and usage state.
2. Parse targeting, protocol, pool, and session controls from the credentials.
3. Exclude providers that cannot supply the requested geography, network, protocol, or session behavior.
4. Exclude provider servers that the health system has marked unavailable.
5. Select among the remaining routes using the product’s configured provider weights and any active sticky-session binding.

Weights apply only to eligible routes. If Provider A is the only provider with the requested city or UDP support, it receives that traffic regardless of a lower configured weight.

Health exclusion is not request retry

Health checks can disable an unavailable provider server, notify operators, and record the degradation in incident history. This affects route selection for subsequent connections.

The gateway does not replay an in-flight HTTP request or tunnel. A retry could duplicate a purchase, form submission, or other non-idempotent action, and simultaneous automatic retries can amplify an outage. The client should decide whether an operation is safe to repeat, apply bounded exponential backoff with jitter, and choose whether to keep or replace its session ID.

Do not retry every 403

A 403 Forbidden is normally a destination or upstream policy response, not proof that the gateway failed. Retrying the same action with another identity can be unsafe and can violate the destination’s policy.

Geography and capability failures

Country, region, city, and ASN constraints form an intersection. The platform does not silently broaden that intersection or substitute another country. When no eligible route remains, the client receives a proxy error.

For an interactive product, load the package-specific location catalog before generating credentials. For an automated client, treat an unavailable target as a validation failure and deliberately remove only the constraint the business workflow allows you to relax.

Sticky and rotating behavior

An opaque session ID plus a positive TTL asks the gateway to reuse a compatible provider route. The session identity is derived consistently, so the same credential behavior can be used across multiple gateway servers.

Sticky continuity can end when:

• the TTL expires;
• the selected upstream exit becomes unavailable;
• targeting, package, ASN, or session ID changes;
• the session is revoked through the API;
• the upstream provider cannot preserve the exit.

Rotating access means the next connection is free to select another eligible exit. It does not guarantee that every request returns a different IP. In generated proxy requests, omit the session object for rotating eligibility. Sticky TTL values are expressed in seconds and accept 30 through 86400 in the current public contract; there is no separate minimum-rotation-interval control.

Three different balancing layers

Layer	Purpose	Failure behavior
Gateway DNS or load balancer	Distribute clients across operator-hosted proxy servers	Moves new connections between gateways according to operator infrastructure
Upstream routing	Select an eligible provider path inside a product	Excludes incompatible or unhealthy routes before selection
Application retry	Decide whether a failed business operation may be repeated	Remains in the client; the gateway does not replay the operation

For credential syntax, continue with targeting and sticky sessions. For returned errors, see proxy errors and troubleshooting.