Backpressure
Capacity limits, backpressure handling, and the CONTROLLER_AT_CAPACITY error.
Backpressure
The Controller enforces capacity limits to prevent overload.
Limits
| Limit | Default | Description |
|---|---|---|
maxInflightPerSession | 32 | Max concurrent tool calls per session |
maxInstances | 10 | Max concurrent instances |
openTimeoutMs | 60000 (60s) | Timeout for opening an instance |
When limits are exceeded
When a limit is exceeded, the Controller returns a CONTROLLER_AT_CAPACITY error. This is a retryable error — the caller should back off and retry.
Best practices
- Set
maxInstancesbased on your machine's resources - Set
maxInflightPerSessionbased on your app's concurrency model - Monitor
CONTROLLER_AT_CAPACITYerrors to know when to scale - Use cluster mode or ShardRouterRuntime to scale horizontally
Next steps
- Error codes — full error reference
- Execution modes — scaling strategies