Rotation Engine
Rotation Policies
Configure session limits, rotate-on-status behavior, cooldown, quarantine, fallback, and concurrency.
Rotation policies control how aggressively the runtime changes proxies and how it treats failures.
Balanced Rotation Policy
The default policy is rotation-policy-balanced.
| Setting | Default |
|---|---|
| Startup validation | Disabled |
| Expected status | 200 |
| Request timeout | 20 seconds |
| Connect timeout | 12 seconds |
| Health check interval | 30 seconds |
| Max requests per session | 1 |
| Max session seconds | 300 |
| Max bytes per session | 50 MB |
| Sticky by target host | Disabled |
| Failure threshold | 2 |
| Retry budget | 1 |
| Rotate on statuses | 403, 429, 502, 503, 504 |
| Cooldown | 30 seconds |
| Quarantine | 300 seconds |
| Max concurrent requests per proxy | 4 |
| Fallback | Enabled |
The default Balanced Rotation policy cannot be deleted.
Policies that are in use cannot be deleted. Max bytes per session is normalized and supports very large caps, up to about 1 TiB.
Complete Policy Fields
| Field | Use |
|---|---|
| Startup validation | Pre-probe proxies before runtime use. |
| Probe URL | Target used for health checks. |
| Expected status codes | Successful probe statuses. |
| Request timeout | Whole request timeout for forwarded requests. |
| Connect timeout | Dial and tunnel timeout. |
| Health interval | How often proxies are health-checked. |
| Max requests/session | Rotates after a session uses a proxy this many times. |
| Max session seconds | Rotates after a session age limit. |
| Max bytes/session | Rotates after a session byte limit. |
| Sticky by target host | Keeps separate sessions per target host. |
| Failure threshold | Repeated failures before quarantine. |
| Retry budget | Alternate proxy attempts after route/dial failure. |
| Rotate-on statuses | Status codes that trigger rotation and session reset. |
| Cooldown seconds | Short pause after a failure below quarantine threshold. |
| Quarantine seconds | Longer pause after failure threshold. |
| Max concurrent requests/proxy | Per-proxy active request limit. |
| Fallback enabled | Allows fallback sources when primary sources are exhausted. |
Key Policy Choices
| Need | Change |
|---|---|
| New proxy every request | Keep max requests per session at 1. |
| Keep target sessions stable | Enable sticky by target host and increase session limits. |
| Avoid bad proxies longer | Increase quarantine seconds. |
| Recover faster | Lower cooldown or quarantine cautiously. |
| Reduce pressure on proxies | Lower max concurrent requests per proxy. |
| React to target blocks | Keep 403 and 429 in rotate-on status codes. |
Cooldown vs Quarantine
Cooldown is a temporary pause after a failure. Quarantine is a stronger pause after the failure threshold is reached. The runtime avoids cooling and quarantined proxies while selecting candidates.
Aggressive rotation does not fix bad source quality. Remove consistently failing proxies from the source pool.