nautechsystems/nautilus_trader · error · anyhow::Error

AX maintenance_margin_pct

Error message

AX maintenance_margin_pct {maintenance_margin_pct} exceeds initial_margin_pct {initial_margin_pct}

What it means

parse_margin_rates enforces the invariant maintenance_margin_pct <= initial_margin_pct; maintenance margin exceeding initial margin is economically inconsistent (you would be liquidated before reaching full position margin).

Solutions

1. Verify which field is initial vs maintenance in the raw payload; check for swapped values.
2. Fix the source data or fixture so maintenance <= initial.
3. Check units: both must be percentages in the same representation (e.g. 10 for 10% vs 0.10).
4. If the venue changed semantics, update the adapter mapping accordingly.

Example fix

// before (payload)
{ "margin_init_pct": "0.05", "margin_maint_pct": "0.10" }
// after
{ "margin_init_pct": "0.10", "margin_maint_pct": "0.05" }

fn margins_consistent(init: Decimal, maint: Decimal) -> bool {
    init > Decimal::ZERO && maint > Decimal::ZERO && maint <= init
}

When it happens

Trigger: parse_instrument (via request_instruments/request_instrument) on a definition where maintenance_margin_pct > initial_margin_pct, e.g. initial 0.05 and maintenance 0.10.

Common situations: Swapped fields in venue metadata or in a hand-built fixture, unit confusion (one value expressed as percent, other as fraction), or venue data-entry error.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• AX final-settlement fill must also be classified as a block…
• AX initial_margin_pct must be positive, was
• AX maintenance_margin_pct must be positive, was
• command client order ID
• Invalid leverage for

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

Appendix: source

Thrown at crates/adapters/architect_ax/src/http/parse.rs:385

        .build()
        .unwrap();

    Ok(InstrumentAny::PerpetualContract(instrument))
}

fn parse_margin_rates(
    initial_margin_pct: Decimal,
    maintenance_margin_pct: Decimal,
) -> anyhow::Result<(Decimal, Decimal)> {
    anyhow::ensure!(
        initial_margin_pct > Decimal::ZERO,
        "AX initial_margin_pct must be positive, was {initial_margin_pct}"
    );
    anyhow::ensure!(
        maintenance_margin_pct > Decimal::ZERO,
        "AX maintenance_margin_pct must be positive, was {maintenance_margin_pct}"
    );
    anyhow::ensure!(
        maintenance_margin_pct <= initial_margin_pct,
        "AX maintenance_margin_pct {maintenance_margin_pct} exceeds initial_margin_pct {initial_margin_pct}"
    );

    Ok((
        margin_percent_to_rate(initial_margin_pct, "initial_margin_pct")?,
        margin_percent_to_rate(maintenance_margin_pct, "maintenance_margin_pct")?,
    ))
}

fn margin_percent_to_rate(value: Decimal, field: &str) -> anyhow::Result<Decimal> {
    let normalized = value.normalize();
    let scale = normalized.scale();
    anyhow::ensure!(
        scale <= 26,
        "AX {field} scale must not exceed 26 for exact percent conversion, was {scale}"
    );
    Decimal::try_from_i128_with_scale(normalized.mantissa(), scale + 2)

View on GitHub (pinned to 18893faf8b)