nautechsystems/nautilus_trader · error

Binance Spot order-book depth must be between 1 and 5000

Error message

Binance Spot order-book depth must be between 1 and 5000

What it means

`request_book_snapshot` validates the optional depth (limit) parameter before calling Binance's /api/v3/depth: if a depth is supplied and is 0 or greater than 5000 it bails, because Binance Spot only accepts limit values in [1, 5000] (with valid discrete limits like 5, 10, 20, 50, 100, 500, 1000, 5000).

Source

Thrown at crates/adapters/binance/src/spot/http/client.rs:3045

            .request_binance_bars(bar_type, start, end, limit)
            .await?
            .into_iter()
            .map(|bar| bar.bar())
            .collect())
    }

    /// Requests an explicit L2 order-book snapshot.
    ///
    /// # Errors
    ///
    /// Returns an error for an invalid depth, missing instrument, request failure, or invalid level.
    pub async fn request_book_snapshot(
        &self,
        instrument_id: InstrumentId,
        depth: Option<u32>,
    ) -> anyhow::Result<OrderBook> {
        if depth.is_some_and(|value| value == 0 || value > 5000) {
            anyhow::bail!("Binance Spot order-book depth must be between 1 and 5000");
        }
        let instrument = self.instrument_from_cache_by_id(instrument_id)?;
        let params = DepthParams {
            symbol: instrument_id.symbol.to_string(),
            limit: depth,
        };
        let snapshot = self.inner.depth(&params).await?;
        let ts_event = self.generate_ts_init();
        Self::parse_book_snapshot_response(instrument_id, &instrument, &snapshot, ts_event)
    }

    fn parse_book_snapshot_response(
        instrument_id: InstrumentId,
        instrument: &InstrumentAny,
        snapshot: &BinanceDepth,
        ts_event: UnixNanos,
    ) -> anyhow::Result<OrderBook> {
        let sequence = u64::try_from(snapshot.last_update_id)

View on GitHub (pinned to 18893faf8b)

Solutions

1. Pass a depth between 1 and 5000 (Binance accepts specific values: 1, 5, 10, 20, 50, 100, 500, 1000, 5000)
2. Pass None to use the adapter/API default depth instead of an explicit invalid value
3. Clamp/validate the configured depth before calling request_book_snapshot

Example fix

// before
let book = client.request_book_snapshot(instrument_id, Some(10_000)).await?;
// after
let book = client.request_book_snapshot(instrument_id, Some(5_000)).await?;

fn valid_book_depth(depth: Option<u32>) -> Option<u32> {
    depth.filter(|d| (1..=5000).contains(d))
}

When it happens

Trigger: Calling `request_book_snapshot(instrument_id, Some(depth))` with depth == 0 or depth > 5000 — e.g. `Some(0)`, `Some(10000)`, or a user-configured book depth of 10000.

Common situations: Configuring an OrderBook depth from a config file where 0 means 'unlimited' in the user's mind; copying Futures depth limits (which cap at 5000 levels differently or accept different values) to Spot; off-by-one or multiplier mistakes when generating depth configs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Conditional orders require a trigger price
• invalid depth {depth}; valid values are {BYBIT_BOOK_DEPTHS:?
• invalid Binance Futures order-book depth {depth}; valid valu
• Binance Spot L1_MBP supports depth 1 only
• invalid negative order-book update ID

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/c6f2494f5939aa8e. Report an issue: GitHub.