What causes "Bybit API error {}: {}" in nautechsystems/nautilus_trader?

Read the ret_code in the error message and look it up in Bybit's API docs for the precise cause

Bybit API error {}: {}

Error message

Bybit API error {}: {}

What it means

Every Bybit HTTP response carries retCode/retMsg; retCode 0 means success. parse_response deserializes the envelope and, for any non-zero retCode, bails with a formatted error containing the venue code and message — this is how Bybit API-level rejections surface in the adapter.

Source

Thrown at crates/adapters/bybit/src/http/parse.rs:31

//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Parsing functions for Bybit HTTP API responses.

use serde::de::DeserializeOwned;

use super::models::{
    BybitInstrumentInverseResponse, BybitInstrumentLinearResponse, BybitInstrumentOptionResponse,
    BybitInstrumentSpotResponse, BybitKlinesResponse, BybitServerTimeResponse,
    BybitTickersLinearResponse, BybitTickersOptionResponse, BybitTickersSpotResponse,
    BybitTradesResponse,
};
use crate::common::models::BybitResponse;

fn parse_response<T: DeserializeOwned>(data: &[u8]) -> anyhow::Result<BybitResponse<T>> {
    let response = serde_json::from_slice::<BybitResponse<T>>(data)?;
    if response.ret_code != 0 {
        anyhow::bail!(
            "Bybit API error {}: {}",
            response.ret_code,
            response.ret_msg
        );
    }
    Ok(response)
}

/// Parses a Bybit server time response from raw JSON bytes.
///
/// # Errors
///
/// Returns an error if deserialization or validation fails.
pub fn parse_server_time_response(data: &[u8]) -> anyhow::Result<BybitServerTimeResponse> {
    parse_response(data)
}

/// Parses a Bybit spot instruments response from raw JSON bytes.

View on GitHub (pinned to 18893faf8b)

Solutions

Read the ret_code in the error message and look it up in Bybit's API docs for the precise cause
Verify API key/secret and key permissions (read/trade) for the account
Slow down requests or add backoff if retCode indicates rate limiting (10006)
Fix the request parameters (symbol, category, product type) per the ret_msg

Defensive patterns

Strategy: try-catch

Validate before calling

// cannot be pre-validated; handle after each call
// check ret_code mapping in Bybit API docs

Try / catch

match client.parse_server_time_response(&body) {
    Err(e) if e.to_string().contains("Bybit API error") => {
        let code = extract_ret_code(&e.to_string());
        match code {
            10006 => backoff_and_retry().await?,   // rate limit
            -2015 => return Err(anyhow!("check API key permissions")),
            _ => return Err(e),
        }
    }
    other => other?,
}

Prevention

Map Bybit ret_codes to actionable handling in your error layer
Use API keys with correct scopes and valid expiry
Apply backoff for rate-limit codes
Validate symbol/category parameters against the instruments endpoint before trading calls

When it happens

Trigger: Any API call whose response envelope has retCode != 0, e.g. invalid API key (-2015), rate limit (10006), invalid symbol, insufficient balance, or permission errors, across server-time, instruments, and tickers endpoints.

Common situations: Expired or wrongly-scoped API keys; hitting IP rate limits; querying symbols that do not exist for the product type; Bybit maintenance windows returning error codes.

Related errors

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