Heuristic:Nautechsystems Nautilus trader Inflight Order Check Threshold
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Live_Trading, Reconciliation |
| Last Updated | 2026-02-10 08:30 GMT |
Overview
Reconciliation timing parameter controlling how long to wait before checking in-flight order status with the exchange, with a default of 5000ms and a warning against reducing unless colocated.
Description
The `LiveExecEngineConfig.inflight_check_threshold_ms` parameter defines the time threshold (in milliseconds) beyond which an in-flight order's status is proactively checked with the venue. An "in-flight" order is one that has been submitted locally but whose acknowledgment from the exchange has not yet been received. If this threshold is exceeded, the execution engine queries the exchange for the current order status to detect missed fills, rejections, or network issues.
A companion parameter `inflight_check_interval_ms` (default: 2000ms) controls how frequently the engine runs the in-flight check loop.
Usage
Use this heuristic when:
- Deploying live trading strategies and configuring reconciliation behavior
- Experiencing missed order acknowledgments or phantom orders
- Running on infrastructure that is not colocated with the exchange
The Insight (Rule of Thumb)
- Action: Configure `inflight_check_threshold_ms` in `LiveExecEngineConfig`.
- Value: Default is 5000ms (5 seconds). Do not reduce this unless you are colocated with the exchange.
- inflight_check_interval_ms: Default is 2000ms. Should not be set lower than `inflight_check_threshold_ms`.
- Trade-off: Reducing the threshold increases the frequency of status check API calls, which counts against exchange rate limits and can cause race conditions if network round-trip time is high. Setting it too high means missed acknowledgments take longer to detect.
Reasoning
The round-trip time for an order submission to an exchange and back includes: local processing, network transit to exchange, exchange matching engine processing, network transit back, and local event processing. For non-colocated setups, this can easily be 100-2000ms. Setting the threshold below the typical round-trip time would cause unnecessary status checks (wasting rate limit budget) and potentially race conditions where the check response arrives before the original order acknowledgment.
The 5000ms default provides a generous buffer that accommodates network jitter, exchange processing delays, and temporary congestion. Only colocated systems (with sub-millisecond round-trip times) can safely reduce this value.
The `reconciliation_lookback_mins` parameter (default: None/max available) controls how far back in time the engine looks when performing a full state reconciliation on startup.
Code Evidence
Configuration documentation from `live/config.py:106-113`:
inflight_check_interval_ms : NonNegativeInt, default 2_000
The interval (milliseconds) between checking whether in-flight orders
have exceeded their time-in-flight threshold.
This should not be set less than the `inflight_check_threshold_ms`.
inflight_check_threshold_ms : NonNegativeInt, default 5_000
The threshold (milliseconds) beyond which an in-flight orders status
is checked with the venue.
As a rule of thumb, you shouldn't consider reducing this setting unless
you are colocated with the venue (to avoid the potential for race conditions).
Default values from `live/config.py:202-203`:
inflight_check_interval_ms: NonNegativeInt = 2_000
inflight_check_threshold_ms: NonNegativeInt = 5_000