Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion kb/technical/how-do-i-implement-sticky-sessions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@ Parameters Explained:
- session-37: Unique session identifier
- sessionttl-30: 30-minute session duration
- sessionmode-flex: Flexible session mode
- Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5)
- Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5)
3 changes: 2 additions & 1 deletion kb/technical/when-do-sticky-sessions-change-nodes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,5 @@ Sessions may change under these conditions:
3. Node unavailability
4. Mode-specific conditions:
- Flex Mode: After 15 consecutive errors
- Strict Mode: Immediate change on failure
- Strict Mode: Immediate change on failure
- No-Rotate Mode: The node does not change until TTL expires
32 changes: 27 additions & 5 deletions residential/sticky-sessions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ curl -x https://network.joinmassive.com:65535 \
When a session identifier is specified and found, the server will perform a request via the same node unless:

* TTL is expired (sessions expire exactly at creation time + TTL)
* The request limit per minute for the node is exceeded
* The node has gone offline
* The request limit per minute for the node is exceeded (only for strict mode)
* The node has gone offline (except in norotate mode)
* Error limit is reached (in flex mode)

If the session identifier is not found or the conditions above are not met, a new session is created with the specified ID and attached to a new node.
Expand All @@ -45,7 +45,7 @@ If the session identifier is not found or the conditions above are not met, a ne

| Key | Value | Description |
| ----------- | ---------------- | ----------- |
| sessionmode | `strict`, `flex` | Controls session behavior on errors |
| sessionmode | `strict`, `flex`, `norotate` | Controls session behavior on errors |

### Strict Mode (Default)

Expand Down Expand Up @@ -87,6 +87,25 @@ curl -x https://network.joinmassive.com:65535 \
https://cloudflare.com/cdn-cgi/trace
```

### No-Rotate Mode

Sessions can operate in **norotate mode** where node errors cause immediate failure instead of rotation. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. Note that TTL expiry still creates a new session (same as other modes).

- Returns **502** on tunnel errors (node responds with an error) or **503** when the node has gone offline
- The `sessionerr` parameter is ignored in norotate mode — any error fails immediately

<Warning>
**Consistent auth strings required:** Session parameters (including `sessionmode`) are re-parsed from the auth string on every request. If you omit `sessionmode-norotate` on a subsequent request using the same session ID, the session silently falls back to **strict** mode and may rotate to a new node on failure. Always include `sessionmode-norotate` in every request for the session.
</Warning>

Example with `sessionmode-norotate`:

```bash
curl -x https://network.joinmassive.com:65535 \
-U '{PROXY_USERNAME}-session-123-sessionmode-norotate:{API_KEY}' \
https://cloudflare.com/cdn-cgi/trace
```

## Additional Parameters

| Key | Value | Description | Default |
Expand All @@ -108,7 +127,7 @@ This example allows up to 5 consecutive errors before rotating to a new node.
## Best Practices

1. **Plan TTL appropriately**: Since sessions use static TTL (not extended by activity), set an appropriate duration for your use case
2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability
2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need IP consistency on node errors (TTL expiry still rotates)
3. **Monitor error rates**: Adjust `sessionerr` based on your tolerance for retries (default is 15)
4. **Session ID naming**: Use descriptive session IDs to help with debugging and monitoring

Expand All @@ -118,12 +137,15 @@ This example allows up to 5 consecutive errors before rotating to a new node.

The following parameters are only applied when a session is created or rotated, not on existing sessions:
- `sessionttl` - TTL duration
- `sessionmode` - Strict vs flex behavior
- `sessionerr` - Error limit for flex mode
- Geographic parameters (`subdivision`, `zipcode`, etc.)

This means changing these parameters on subsequent requests with the same session ID will have no effect until the session rotates to a new node.

### Parameters Re-parsed on Every Request

`sessionmode` is evaluated on every request, not just at session creation (see the [norotate warning](#no-rotate-mode) above).

### Session-Breaking Parameters

<Warning>
Expand Down