nautechsystems/nautilus_trader · error

Order detail returned {} records for one identifier

Error message

Order detail returned {} records for one identifier

What it means

After fetching order detail, the adapter expects the response to contain at most one record since the query targeted a single order ID. If OKX returns multiple records for one identifier, the adapter treats it as an API contract violation and bails, since it cannot determine which record represents the order.

Source

Thrown at crates/adapters/okx/src/http/client.rs:4391

                params_builder.ord_id(venue_order_id.as_str().to_string());
            }
            _ => anyhow::bail!(
                "Exactly one of client_order_id or venue_order_id is required for an order detail request"
            ),
        }

        let params = params_builder
            .build()
            .map_err(|e| anyhow::anyhow!("Failed to build order detail params: {e}"))?;
        let orders = match self.inner.get_order(params).await {
            Ok(orders) => orders,
            Err(e) if e.is_order_not_found() => return Ok(None),
            Err(e) => return Err(e.into()),
        };
        let order = match orders.as_slice() {
            [] => return Ok(None),
            [order] => order,
            _ => anyhow::bail!(
                "Order detail returned {} records for one identifier",
                orders.len(),
            ),
        };

        if order.inst_id.as_str() != instrument_id.symbol.inner() {
            anyhow::bail!(
                "Order detail instrument mismatch for {instrument_id}: returned {}",
                order.inst_id,
            );
        }

        if let Some(venue_order_id) = venue_order_id
            && order.ord_id.as_str() != venue_order_id.as_str()
        {
            anyhow::bail!(
                "Order detail venue order ID mismatch for {venue_order_id}: returned {}",
                order.ord_id,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Query with the unique venue_order_id (ordId) instead of client_order_id to guarantee a single record
2. Log the response and retry the request once — a transient duplicate may resolve
3. If it persists, treat it as an exchange-side anomaly: report/inspect the raw response and contact OKX support

match client.request_order_detail(instrument_id, None, Some(void)).await {
    Ok(report) => { /* use */ }
    Err(e) if e.to_string().contains("Order detail returned") => {
        // duplicate records for one identifier: retry or escalate
        log::warn!("ambiguous order detail response: {e}");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: request_order_detail receives an OKX response whose orders array has more than one element for the single clOrdId/ordId queried (observed after the [] and [order] match arms fail).

Common situations: OKX API behavior changes or archival/query quirks returning duplicates; requesting by a non-unique clOrdId after clientOrderId reuse; unexpected exchange-side state.

Related errors

• Failed to request open orders for perm_id lookup: {e}
• Failed to get open orders: {error_msg}
• Exactly one of client_order_id or venue_order_id is required
• Order detail instrument mismatch for {instrument_id}: return
• Order detail venue order ID mismatch for {venue_order_id}: r

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