nautechsystems/nautilus_trader · error · anyhow::Error

Binance Spot trade limit must not exceed 1000

Error message

Binance Spot trade limit must not exceed 1000

What it means

Binance Spot GET /api/v3/trades and /api/v3/aggTrades cap the `limit` query parameter at 1000. The adapter validates the request's limit (converted to u32) before spawning the request task, so an over-limit value fails fast with a clear message instead of a venue-side 400 'Limit exceeds max limit'.

Source

Thrown at crates/adapters/binance/src/spot/data.rs:2306

            }
        });
        Ok(())
    }

    fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
        let http = self.http_client.clone();
        let sender = self.data_sender.clone();
        let instrument_id = request.instrument_id;
        let limit = request.limit.map(|n| n.get() as u32);
        let request_id = request.request_id;
        let client_id = request.client_id.unwrap_or(self.client_id);
        let params = request.params;
        let clock = self.clock;
        let start_nanos = datetime_to_unix_nanos(request.start);
        let end_nanos = datetime_to_unix_nanos(request.end);
        let start = request.start;
        let end = request.end;
        anyhow::ensure!(
            limit.is_none_or(|value| value <= 1000),
            "Binance Spot trade limit must not exceed 1000"
        );

        get_runtime().spawn(async move {
            let result = if start.is_some() || end.is_some() {
                http.request_agg_trades(instrument_id, start, end, limit)
                    .await
            } else {
                http.request_trades(instrument_id, limit).await
            };

            match result.context("failed to request trades from Binance") {
                Ok(trades) => {
                    let response = DataResponse::Trades(TradesResponse::new(
                        request_id,
                        client_id,
                        instrument_id,

View on GitHub (pinned to a4b06ed870)

Solutions

1. Set limit to 1000 or less (Binance's default is 500 when unset)
2. For larger backfills, paginate with start/end windows or fromId cursors via aggTrades and merge client-side
3. Clamp any user-supplied page size against the venue cap before constructing the request

Example fix

// before
let request = RequestTradeTicks { limit: Some(NonZeroU64::new(5000)?), .. };

// after: Binance Spot caps trades/aggTrades at 1000
let request = RequestTradeTicks { limit: Some(NonZeroU64::new(1000)?), .. };

const BINANCE_SPOT_TRADE_LIMIT_MAX: u32 = 1000;

fn clamp_trade_limit(limit: Option<u32>) -> Option<u32> {
    limit.map(|l| l.min(BINANCE_SPOT_TRADE_LIMIT_MAX))
}

When it happens

Trigger: Calling request_trade_ticks (RequestTradeTicks) with limit > 1000, with or without start/end timestamps: both the aggTrades and plain trades branches are gated by the same ensure! at spot/data.rs:2306.

Common situations: Copying a limit constant from a venue with a higher cap (some allow 5000-10000); backfill scripts that try to fetch 'as much as possible' in a single call; UIs defaulting to large page sizes.

Related errors

• Binance Spot order-book depth must be between 1 and 5000
• Binance Futures trade limit must not exceed 1000
• Spot ticker requires a BINANCE instrument
• Binance Spot L1_MBP supports depth 1 only
• Binance Spot supports L1_MBP and L2_MBP order book subscript

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/eee82fbe4bfcae46. Report an issue: GitHub.