rustrade_execution/

error.rs

//! Error types for [`ExecutionClient`](super::client::ExecutionClient) operations.
//!
//! # Retry Semantics
//!
//! Use [`ClientError::is_transient`] to determine if an operation should be retried.
//! Transient errors (connectivity issues, rate limits) may succeed on retry with
//! appropriate backoff. Non-transient errors (invalid instrument, insufficient
//! balance) will fail identically on retry — the caller must change the request.
//!
//! The `is_transient()` method is the stable contract for retry decisions. Prefer
//! it over pattern matching on specific variants, as the internal taxonomy may
//! evolve while `is_transient()` semantics remain stable.

use derive_more::Constructor;
use rust_decimal::Decimal;
use rustrade_instrument::{
    asset::{AssetIndex, name::AssetNameExchange},
    exchange::ExchangeId,
    index::error::IndexError,
    instrument::{InstrumentIndex, name::InstrumentNameExchange},
};
use rustrade_integration::error::SocketError;
use serde::{Deserialize, Serialize};
use std::{fmt, time::Duration};
use thiserror::Error;

/// Type alias for a [`ClientError`] that is keyed on [`AssetNameExchange`] and
/// [`InstrumentNameExchange`] (yet to be indexed).
pub type UnindexedClientError = ClientError<AssetNameExchange, InstrumentNameExchange>;

/// Type alias for a [`ApiError`] that is keyed on [`AssetNameExchange`] and
/// [`InstrumentNameExchange`] (yet to be indexed).
pub type UnindexedApiError = ApiError<AssetNameExchange, InstrumentNameExchange>;

/// Type alias for a [`OrderError`] that is keyed on [`AssetNameExchange`] and
/// [`InstrumentNameExchange`] (yet to be indexed).
pub type UnindexedOrderError = OrderError<AssetNameExchange, InstrumentNameExchange>;

/// Represents all errors produced by an [`ExecutionClient`](super::client::ExecutionClient).
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum ClientError<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    /// Connectivity based error.
    ///
    /// eg/ Timeout.
    #[error("Connectivity: {0}")]
    Connectivity(#[from] ConnectivityError),

    /// API based error.
    ///
    /// eg/ RateLimit.
    #[error("API: {0}")]
    Api(#[from] ApiError<AssetKey, InstrumentKey>),

    /// A background task panicked or was cancelled during an operation.
    ///
    /// This indicates a bug or unexpected runtime condition (e.g., a tokio
    /// `spawn_blocking` task panicked). The operation was not retried and
    /// the caller should treat this as non-recoverable, requiring operator
    /// attention.
    #[error("task failed: {0}")]
    TaskFailed(String),

    /// An opaque error from an upstream library that cannot be further classified.
    ///
    /// This is a catch-all for errors that don't fit into [`Self::Connectivity`] or
    /// [`Self::Api`] categories — typically because the upstream library (e.g., ibapi,
    /// binance-sdk) returns unstructured errors.
    ///
    /// Conservatively treated as non-transient. If you encounter this error
    /// frequently, consider filing an issue to improve error classification.
    #[error("internal error: {0}")]
    Internal(String),

    /// A bounded read of fills could not advance past its start: more fills share the span's
    /// first moment than one call can read, so a read from the same start would stop at the same
    /// place.
    ///
    /// [`ExecutionClient::fetch_trades`](crate::client::ExecutionClient::fetch_trades) returns it
    /// rather than a [`TradesRead`](crate::trade::TradesRead) whose `resume` could only loop. The
    /// fills it read are not returned. Callers should alert operators and reconcile the span
    /// another way.
    #[error("trade read stopped after {fills_read} fills without advancing past its start")]
    Truncated {
        /// How many fills the read returned before it stopped.
        fills_read: usize,
    },

    /// Open orders snapshot was truncated at the API's row limit.
    ///
    /// Unlike [`Self::Truncated`] (which applies to paginated fill reads), this
    /// error indicates a single-request endpoint hit its maximum row count.
    /// Alpaca's `/v2/orders` endpoint caps results at 500; accounts with more
    /// concurrent open orders will have an incomplete snapshot.
    ///
    /// Callers should alert operators — an incomplete order snapshot can cause
    /// duplicate submissions, missed cancellations, or incorrect position sizing.
    #[error("open orders snapshot truncated at {limit} results — data may be incomplete")]
    TruncatedSnapshot {
        /// Maximum number of rows returned by the single-request endpoint.
        limit: usize,
    },
}

impl<AssetKey, InstrumentKey> ClientError<AssetKey, InstrumentKey> {
    /// Returns `true` if this error is likely transient and the operation
    /// may succeed if retried after a suitable backoff.
    ///
    /// The caller is responsible for retry limits and backoff strategy.
    /// This method classifies the error only — it does not implement policy.
    ///
    /// # Transient errors
    /// - [`Connectivity`](Self::Connectivity) errors (timeout, socket, offline)
    /// - [`Api::RateLimit`](ApiError::RateLimit), though not before its `retry_after`
    ///
    /// # Non-transient errors
    /// - Other [`Api`](Self::Api) errors (invalid instrument, insufficient balance, etc.)
    /// - [`TaskFailed`](Self::TaskFailed) (indicates a bug)
    /// - [`Internal`](Self::Internal) (unknown — conservatively non-transient)
    /// - [`Truncated`](Self::Truncated) / [`TruncatedSnapshot`](Self::TruncatedSnapshot)
    pub fn is_transient(&self) -> bool {
        match self {
            Self::Connectivity(e) => e.is_transient(),
            Self::Api(ApiError::RateLimit { .. }) => true,
            Self::Api(_) => false,
            Self::TaskFailed(_) => false,
            Self::Internal(_) => false,
            Self::Truncated { .. } => false,
            Self::TruncatedSnapshot { .. } => false,
        }
    }
}

/// Represents all connectivity-centric errors.
///
/// Connectivity errors are generally intermittent / non-deterministic (eg/ Timeout).
/// All variants are transient — retry with exponential backoff (typically 1-30s).
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum ConnectivityError {
    /// Exchange is offline, likely due to scheduled maintenance.
    ///
    /// Transient — retry with backoff. Maintenance windows typically last minutes
    /// to hours; consider longer backoff intervals (30s-5min) to avoid log spam.
    #[error("Exchange offline: {0}")]
    ExchangeOffline(ExchangeId),

    /// Request timed out before a response was received.
    ///
    /// Transient — retry with backoff. May indicate network congestion, server
    /// overload, or an overly aggressive timeout. Consider increasing timeout
    /// on subsequent attempts.
    #[error("request timed out")]
    Timeout,

    /// Network-level socket error (connection refused, reset, DNS failure, etc.).
    ///
    /// Transient — retry with backoff. If persistent, may indicate firewall
    /// issues, incorrect endpoint configuration, or prolonged server outage.
    #[error("{0}")]
    Socket(String),
}

impl From<SocketError> for ConnectivityError {
    fn from(value: SocketError) -> Self {
        Self::Socket(value.to_string())
    }
}

impl ConnectivityError {
    /// Returns `true` if this connectivity error is transient.
    ///
    /// All connectivity errors are considered transient — they represent
    /// temporary network or server conditions that may resolve with retry.
    pub fn is_transient(&self) -> bool {
        match self {
            Self::ExchangeOffline(_) => true,
            Self::Timeout => true,
            Self::Socket(_) => true,
        }
    }
}

/// Represents all API errors generated by an exchange.
///
/// These typically indicate a request is invalid for some reason (eg/ BalanceInsufficient).
/// Most variants are **not transient** — the same request will fail identically on retry.
/// The exception is [`RateLimit`](Self::RateLimit), which is transient.
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum ApiError<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    /// Provided asset identifier is invalid or not supported.
    ///
    /// For example:
    /// - The [`AssetNameExchange`] was an invalid format.
    ///
    /// Not transient — do not retry. The asset identifier must be corrected.
    ///
    /// Indexed only when the [`ExecutionInstrumentMap`] holds the asset. Otherwise there is no
    /// index to carry, and [`AccountEventIndexer`] reports it as
    /// [`OrderRejected`](Self::OrderRejected) (from an order request) or
    /// [`RequestRejected`](Self::RequestRejected) (from any other request), holding this error's
    /// own message.
    ///
    /// [`ExecutionInstrumentMap`]: crate::map::ExecutionInstrumentMap
    /// [`AccountEventIndexer`]: crate::indexer::AccountEventIndexer
    #[error("asset {0} invalid: {1}")]
    AssetInvalid(AssetKey, String),

    /// Provided instrument identifier is invalid or not supported.
    ///
    /// For example:
    /// - The exchange does not have a market for an instrument.
    /// - The [`InstrumentNameExchange`] was an invalid format.
    ///
    /// Not transient — do not retry. The instrument identifier must be corrected.
    ///
    /// Indexed only when the [`ExecutionInstrumentMap`] holds the instrument; otherwise reported
    /// as [`AssetInvalid`](Self::AssetInvalid) describes.
    ///
    /// [`ExecutionInstrumentMap`]: crate::map::ExecutionInstrumentMap
    #[error("instrument {0} invalid: {1}")]
    InstrumentInvalid(InstrumentKey, String),

    /// Request was rejected due to rate limiting.
    ///
    /// The exchange enforces request quotas and the caller has exceeded them. The client may
    /// already have waited and retried within its own bounded retries before surfacing this.
    ///
    /// `retry_after` is the venue's own minimum wait, measured from when the client read the
    /// refusal: do not retry sooner. `None` means the venue sent no hint, or the client cannot
    /// read it, and is not permission to retry at once. Which clients fill it:
    /// - **Alpaca:** from a 429's `Retry-After`, or else `X-RateLimit-Reset`, once the client's
    ///   own retries are exhausted.
    /// - **Binance:** never, for now: `binance-sdk` drops the response headers, `Retry-After`
    ///   among them, from its rate-limit errors.
    /// - **Hyperliquid:** never: its SDK keeps no headers, and Hyperliquid documents no hint.
    ///
    /// A venue ban (Binance's HTTP 418) is reported the same way: its hint, when readable, says
    /// how long it lasts.
    ///
    /// Transient — retry after `retry_after` when given, otherwise with backoff.
    ///
    /// The variant is `#[non_exhaustive]`: outside this crate, build one with
    /// [`ApiError::rate_limited`], match it as `RateLimit { .. }`, and read the wait with
    /// [`ApiError::retry_after`].
    #[error("rate limit exceeded{}", RetryAfter(*retry_after))]
    #[non_exhaustive]
    RateLimit { retry_after: Option<Duration> },

    /// The venue refused because a cap on something held at once is full, such as IBKR's market
    /// data lines, which every TWS session and API client on the account shares.
    ///
    /// Unlike [`RateLimit`](Self::RateLimit), waiting does not clear it: releasing something
    /// does, such as cancelling another subscription, whether this client holds it or another
    /// session on the same account does. The message carries the venue's words.
    ///
    /// Not transient: the same request retried with backoff alone meets the same refusal while
    /// the cap stays full.
    #[error("venue capacity exceeded: {0}")]
    CapacityExceeded(String),

    /// Authentication failed (invalid credentials, expired key, bad signature).
    ///
    /// Unlike other API errors which affect a single request, authentication
    /// failures indicate that **all** subsequent requests will fail until
    /// credentials are corrected. Callers should halt trading and alert operators.
    ///
    /// Not transient — do not retry. Fix credentials and restart.
    #[error("authentication failed: {0}")]
    Unauthenticated(String),

    /// Balance of an asset is insufficient to execute the requested operation.
    ///
    /// The asset is `None` when it is not known which asset ran short:
    /// - the venue's rejection does not name it (e.g. Binance's "Account has insufficient
    ///   balance for requested action", or any Hyperliquid margin or spot-balance refusal), and
    ///   a client does not guess it from the order;
    /// - the venue named an asset that the [`ExecutionInstrumentMap`] does not hold, so it has no
    ///   index. [`AccountEventIndexer::api_error`] logs the name it dropped.
    ///
    /// The `String` carries the venue's message.
    ///
    /// Not transient — do not retry the same request. Reduce order size or
    /// deposit additional funds.
    ///
    /// [`ExecutionInstrumentMap`]: crate::map::ExecutionInstrumentMap
    /// [`AccountEventIndexer::api_error`]: crate::indexer::AccountEventIndexer::api_error
    #[error(
        "balance insufficient{asset}: {1}",
        asset = .0.as_ref().map(|asset| format!(" for asset {asset}")).unwrap_or_default()
    )]
    BalanceInsufficient(Option<AssetKey>, String),

    /// Order was rejected by the exchange for a business rule violation.
    ///
    /// Common causes include: price outside allowed range, quantity below
    /// minimum, post-only order would cross, reduce-only with no position.
    ///
    /// Not transient — do not retry the same request. Adjust order parameters.
    #[error("order rejected: {0}")]
    OrderRejected(String),

    /// Cancel request failed because the order was already cancelled.
    ///
    /// This is a state conflict, not an error per se — the desired end state
    /// (order cancelled) has already been achieved.
    ///
    /// Not transient — do not retry. The order is already in the cancelled state.
    #[error("order already cancelled")]
    OrderAlreadyCancelled,

    /// Cancel request failed because the order was already fully filled.
    ///
    /// This is a state conflict — the order completed before the cancel arrived.
    /// The caller should reconcile their local state with the fill.
    ///
    /// Not transient — do not retry. The order no longer exists to cancel.
    #[error("order already fully filled")]
    OrderAlreadyFullyFilled,

    /// Cancel request failed because the order had already expired.
    ///
    /// This is a state conflict — the order's own deadline retired it before the cancel arrived,
    /// so the desired end state (order no longer working) has already been achieved. Distinct from
    /// [`OrderAlreadyCancelled`](Self::OrderAlreadyCancelled) because nobody asked for it: a
    /// time-in-force such as [`GoodTillDate`](crate::order::TimeInForce::GoodTillDate) retired it
    /// unprompted, and a caller reconciling its local state needs to know which of the two happened.
    ///
    /// Not transient — do not retry. The order no longer exists to cancel.
    #[error("order already expired")]
    OrderAlreadyExpired,

    /// Open request refused because its [`ClientOrderId`] is already in use at the venue.
    ///
    /// The refusal concerns this request alone: the order already under the id is **unaffected**,
    /// and is not reported ended by it. What "in use" means is the venue's rule. On the
    /// [`SimulatedVenue`] and the IBKR client it is an order still working under the id, and an id
    /// is free again once its order has ended. Binance documents an id as unique among open
    /// orders. The `String` carries the venue's message, or the client's own where it refused the
    /// request before sending it.
    ///
    /// Reported by the [`SimulatedVenue`], by the IBKR client, which refuses the request before it
    /// reaches TWS, since TWS never sees a client order id, and by the Binance spot and margin
    /// clients, from Binance's `"Duplicate order sent."`. Other clients report a venue's duplicate
    /// rejection as [`OrderRejected`](Self::OrderRejected) until its message has been confirmed.
    ///
    /// Not transient — the same request fails identically while the order under the id works.
    /// Use another id, or wait for that order to end.
    ///
    /// [`ClientOrderId`]: crate::order::id::ClientOrderId
    /// [`SimulatedVenue`]: crate::exchange::mock::SimulatedVenue
    #[error("client order id in use: {0}")]
    DuplicateClientOrderId(String),

    /// The exchange refused the request itself, rather than an order it carried.
    ///
    /// The request was malformed or asked for something the venue does not serve — a missing,
    /// malformed or out-of-range parameter, such as a query time window longer than the venue
    /// allows. Distinct from [`OrderRejected`](Self::OrderRejected), which is an order failing a
    /// business rule; this variant arises from queries and other non-order requests. The message
    /// carries the venue's own error code where it provides one (e.g. `-1127 ...` on Binance).
    ///
    /// Not transient — the same request fails identically on retry. Change the request.
    #[error("request rejected: {0}")]
    RequestRejected(String),

    /// Order refused because the venue would not lend what it needed: a short sale, or a margin
    /// order that borrows to cover itself.
    ///
    /// Distinct from [`OrderRejected`](Self::OrderRejected) so a caller can tell a refused borrow
    /// apart from a malformed order, and from [`BalanceInsufficient`](Self::BalanceInsufficient),
    /// which is the account's own funds running short. A borrow can be refused for a long too: on
    /// Binance margin, an order that borrows to buy is refused when the venue has too little of
    /// the asset to lend or the borrow would exceed the account's limit. [`BorrowReject`] says
    /// why.
    ///
    /// Reported by the Binance margin client, by Binance's code, by the Alpaca client, by the
    /// text of a 403 or 422, and by the
    /// [`SimulatedVenue`](crate::exchange::mock::SimulatedVenue), for a CFD short its
    /// [`ShortabilityProvider`](crate::shortability::ShortabilityProvider) does not allow. Other
    /// clients report such refusals as [`OrderRejected`](Self::OrderRejected) until their venue's
    /// wording is confirmed.
    ///
    /// Not transient — the same request fails identically until the venue's lending changes.
    #[error("borrow rejected: {0}")]
    BorrowRejected(BorrowReject),
}

impl<AssetKey, InstrumentKey> ApiError<AssetKey, InstrumentKey> {
    /// A [`RateLimit`](Self::RateLimit) refusal, with the venue's minimum wait when it sent one.
    pub fn rate_limited(retry_after: Option<Duration>) -> Self {
        Self::RateLimit { retry_after }
    }

    /// The venue's minimum wait before a retry: `Some` only for a
    /// [`RateLimit`](Self::RateLimit) whose venue sent a hint the client could read.
    pub fn retry_after(&self) -> Option<Duration> {
        match self {
            Self::RateLimit { retry_after } => *retry_after,
            _ => None,
        }
    }
}

/// Formats a [`RateLimit`](ApiError::RateLimit)'s hint for its message: nothing when there is
/// none.
struct RetryAfter(Option<Duration>);

impl fmt::Display for RetryAfter {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.0 {
            Some(retry_after) => write!(f, "; retry after {retry_after:?}"),
            None => Ok(()),
        }
    }
}

/// Why a venue refused to lend for an order, as carried by [`ApiError::BorrowRejected`].
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)]
pub struct BorrowReject {
    /// The kind of refusal.
    pub reason: BorrowRejectReason,
    /// The venue's own code for the refusal, where it gave one (e.g. `-3045` on Binance,
    /// `40310000` on Alpaca).
    ///
    /// For diagnostics only, not a stable contract: match on [`reason`](Self::reason) instead. A
    /// venue may reuse a code for several refusals, as Alpaca's generic `40310000` is.
    pub venue_code: Option<String>,
    /// The venue's message. It may itself carry the code, as Binance's does.
    pub message: String,
    /// How much the venue could still have lent, in the units the order was sized in, where
    /// known: the most a smaller order could have sold short. Set by the simulated venue; no live
    /// client reports it yet.
    pub available: Option<Decimal>,
}

impl BorrowReject {
    /// A refusal for `reason`, with the venue's code where it gave one, and its message.
    pub fn new(reason: BorrowRejectReason, venue_code: Option<String>, message: String) -> Self {
        Self {
            reason,
            venue_code,
            message,
            available: None,
        }
    }

    /// With how much the venue could still have lent.
    #[must_use]
    pub fn with_available(mut self, available: Decimal) -> Self {
        self.available = Some(available);
        self
    }
}

impl fmt::Display for BorrowReject {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Self {
            reason,
            venue_code,
            message,
            available,
        } = self;
        write!(f, "{reason}")?;
        if let Some(code) = venue_code {
            write!(f, " (code {code})")?;
        }
        write!(f, ": {message}")?;
        if let Some(available) = available {
            write!(f, " ({available} available)")?;
        }
        Ok(())
    }
}

/// The kind of borrow refusal carried by a [`BorrowReject`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)]
pub enum BorrowRejectReason {
    /// The instrument cannot be sold short at all, whoever asks (e.g. Alpaca's "asset X cannot be
    /// sold short").
    NotShortable,
    /// Borrowing is barred for this account, or for this asset on this account (e.g. Binance
    /// `-3008`, `-3012` and `-3014`, Alpaca's "account is not allowed to short").
    BorrowDisabled,
    /// The venue has too little of the asset to lend right now (e.g. Binance `-3045`). It may
    /// lend again later.
    InventoryUnavailable,
    /// The borrow would exceed what the account may borrow (e.g. Binance `-3006`).
    BorrowLimitExceeded,
    /// A short-sale restriction is in effect, such as the SEC's Rule 201 circuit breaker after a
    /// 10% fall, and the order would sell short at or below the best bid. A short sale priced
    /// above the bid may still be accepted.
    ShortSaleRestricted,
    /// A borrow refusal of a kind not listed here. The [`BorrowReject`] message says which.
    Other,
}

impl fmt::Display for BorrowRejectReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::NotShortable => "not shortable",
            Self::BorrowDisabled => "borrow disabled",
            Self::InventoryUnavailable => "inventory unavailable",
            Self::BorrowLimitExceeded => "borrow limit exceeded",
            Self::ShortSaleRestricted => "short sale restricted",
            Self::Other => "other",
        })
    }
}

/// Represents all errors that can be generated when cancelling or opening orders.
///
/// This is a subset of [`ClientError`] for order-specific operations. Use
/// [`is_transient()`](Self::is_transient) to determine retry eligibility.
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum OrderError<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    /// Connectivity-based error (timeout, socket failure, exchange offline), or a venue failure
    /// that leaves the order's status unknown.
    ///
    /// Transient — retry with backoff. See [`ConnectivityError`] for details. The order may or
    /// may not have reached the matching engine, so before resubmitting an open request,
    /// reconcile its state (open orders, fills); a blind retry can place it twice.
    #[error("connectivity: {0}")]
    Connectivity(#[from] ConnectivityError),

    /// API-based error (rate limit, invalid instrument, order rejected, etc.).
    ///
    /// Retry semantics depend on the specific [`ApiError`] variant. Only
    /// [`ApiError::RateLimit`] is transient; other variants are not.
    #[error("order rejected: {0}")]
    Rejected(#[from] ApiError<AssetKey, InstrumentKey>),

    /// The order type is not supported by this connector.
    ///
    /// Non-transient — the connector does not support this order type (e.g.,
    /// trailing stop orders on a connector that only supports market/limit).
    #[error("unsupported order type: {0}")]
    UnsupportedOrderType(String),

    /// A quantity or price in the request has more precision than the venue accepts, so the
    /// client refused it without sending it.
    ///
    /// Non-transient — change the request. A client that refuses this way never rounds a value
    /// itself, because rounding would place a different order than the one requested; it
    /// documents how to read the venue's precision so the caller can round first.
    #[error("invalid precision: {0}")]
    InvalidPrecision(PrecisionViolation),
}

/// A value in an order request with more precision than the venue accepts, or that is not
/// positive.
///
/// Carried by [`OrderError::InvalidPrecision`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)]
pub struct PrecisionViolation {
    /// Which value of the request broke the rule.
    pub field: OrderField,
    /// The value as requested.
    pub value: Decimal,
    /// The rule it broke.
    pub limit: PrecisionLimit,
}

impl PrecisionViolation {
    /// The request's `field`, of `value`, breaks `limit`.
    pub fn new(field: OrderField, value: Decimal, limit: PrecisionLimit) -> Self {
        Self {
            field,
            value,
            limit,
        }
    }
}

impl fmt::Display for PrecisionViolation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Self {
            field,
            value,
            limit,
        } = self;
        write!(f, "{field} {value} ")?;
        match limit {
            PrecisionLimit::DecimalPlaces { max } => {
                write!(f, "has more than {max} decimal places")
            }
            PrecisionLimit::SignificantFigures { max } => {
                write!(
                    f,
                    "is not an integer and has more than {max} significant figures"
                )
            }
            PrecisionLimit::NotRepresentable => {
                write!(f, "cannot be sent exactly in the venue's number format")
            }
            PrecisionLimit::NotPositive => write!(f, "is not positive"),
        }
    }
}

/// A value of an order request, as named by a [`PrecisionViolation`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)]
pub enum OrderField {
    /// The order's quantity.
    Quantity,
    /// The order's limit price.
    Price,
    /// The price that triggers a stop or take-profit order.
    TriggerPrice,
    /// A trailing order's offset.
    TrailingOffset,
}

impl fmt::Display for OrderField {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::Quantity => "quantity",
            Self::Price => "price",
            Self::TriggerPrice => "trigger price",
            Self::TrailingOffset => "trailing offset",
        })
    }
}

/// A venue's precision rule, as broken by a [`PrecisionViolation`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)]
pub enum PrecisionLimit {
    /// The value may have at most `max` decimal places.
    DecimalPlaces {
        /// The most decimal places allowed.
        max: u32,
    },
    /// The value may have at most `max` significant figures, unless it is an integer.
    SignificantFigures {
        /// The most significant figures allowed.
        max: u32,
    },
    /// The value cannot be sent exactly: the venue's client library converts it to a number
    /// format that would change it.
    NotRepresentable,
    /// The value is zero or negative. A quantity, price or trailing offset must be positive.
    NotPositive,
}

impl<AssetKey, InstrumentKey> OrderError<AssetKey, InstrumentKey> {
    /// Returns `true` if this error is likely transient and the operation
    /// may succeed if retried after a suitable backoff.
    ///
    /// # Transient errors
    /// - [`Connectivity`](Self::Connectivity) errors (timeout, socket, offline)
    /// - [`Rejected(ApiError::RateLimit)`](ApiError::RateLimit), though not before its
    ///   `retry_after`
    ///
    /// # Non-transient errors
    /// - Other [`Rejected`](Self::Rejected) errors (invalid instrument, insufficient balance,
    ///   refused borrow, etc.)
    /// - [`UnsupportedOrderType`](Self::UnsupportedOrderType) and
    ///   [`InvalidPrecision`](Self::InvalidPrecision)
    pub fn is_transient(&self) -> bool {
        match self {
            Self::Connectivity(e) => e.is_transient(),
            Self::Rejected(ApiError::RateLimit { .. }) => true,
            Self::Rejected(_) => false,
            Self::UnsupportedOrderType(_) | Self::InvalidPrecision(_) => false,
        }
    }
}

/// Why an account event stream ended.
///
/// Delivered in-band as the payload of
/// [`AccountEventKind::StreamTerminated`](crate::AccountEventKind::StreamTerminated) so that
/// stream death is a programmatic signal on the account feed rather than a log-only event. A
/// consumer can react (re-sync via REST, re-establish the stream, halt trading) according to its
/// own policy — the library reports *why* the stream ended without prescribing the response.
///
/// # Only in-band-deliverable terminations are represented
///
/// Every variant here is a termination the library can actually deliver to a consumer that is
/// still listening. A consumer-initiated drop is deliberately **not** a variant: by the time a
/// stream task observes the drop, the receiving half of the channel is already gone, so a
/// `StreamTerminated` send would be a guaranteed no-op. `StreamTerminated` therefore always means
/// "the stream died while you were still listening".
///
/// `#[non_exhaustive]` so venues may distinguish further termination causes in future without a
/// breaking change (e.g. a venue able to signal a graceful shutdown over a still-open channel).
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum StreamTerminationReason {
    /// A venue with built-in reconnection exhausted its retry budget and gave up.
    ///
    /// Emitted by venues that reconnect internally (e.g. Binance spot/margin, Alpaca) once the
    /// final attempt fails. `last_error` is the most recent underlying failure; `attempts` is the
    /// number of reconnects tried before surrendering. The stream will not recover on its own —
    /// the consumer must re-establish it.
    #[error("reconnect budget exhausted after {attempts} attempts: {last_error}")]
    ReconnectBudgetExhausted {
        /// Number of reconnect attempts made before giving up.
        attempts: u32,
        /// The most recent underlying error that triggered surrender.
        last_error: String,
    },

    /// The stream ended on an unrecoverable error with no automatic recovery.
    ///
    /// Emitted by venues without library-managed reconnection — e.g. IBKR (the underlying
    /// subscription errored and the client does not retry), Hyperliquid (the SDK's internal
    /// reconnection gave up and closed the channel), or the mock exchange (its broadcast stream
    /// lagged past the buffer). The consumer is responsible for any re-establishment.
    #[error("unrecoverable stream error: {0}")]
    Error(String),
}

/// Type alias for an [`AccountStreamInitError`] that is keyed on [`AssetNameExchange`] and
/// [`InstrumentNameExchange`] (yet to be indexed).
pub type UnindexedAccountStreamInitError =
    AccountStreamInitError<AssetNameExchange, InstrumentNameExchange>;

/// Why an attempt to initialise an account stream, its snapshot and its updates, failed.
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum AccountStreamInitError<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    /// The [`ExecutionClient`](crate::client::ExecutionClient) failed to fetch the account
    /// snapshot or to open the account stream. See [`ClientError::is_transient`].
    #[error("{0}")]
    Client(#[from] ClientError<AssetKey, InstrumentKey>),

    /// The account snapshot named an exchange, asset or instrument that is not indexed. This does
    /// not resolve on retry while the venue keeps reporting it.
    #[error("IndexError: {0}")]
    Index(#[from] IndexError),
}

/// A failed attempt to re-initialise an account stream after it ended.
///
/// Delivered in-band as the payload of
/// [`AccountEventKind::ReinitFailed`](crate::AccountEventKind::ReinitFailed), once per failed
/// attempt. Attempts continue with backoff; giving up is the consumer's decision.
#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Constructor)]
pub struct AccountReinitFailure<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    /// Consecutive failed attempts since the stream last initialised, starting at 1.
    pub attempt: u32,
    /// Why this attempt failed.
    pub error: AccountStreamInitError<AssetKey, InstrumentKey>,
}

/// Represents errors related to exchange, asset and instrument identifier key lookups.
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize, Error)]
pub enum KeyError {
    /// Indicates an [`ExchangeId`] was encountered that was not indexed, so does not have a
    /// corresponding `ExchangeIndex`.
    #[error("ExchangeId: {0}")]
    ExchangeId(String),

    /// Indicates an [`AssetNameExchange`] was encountered that was not indexed, so does not have a
    /// corresponding [`AssetIndex`].
    #[error("AssetKey: {0}")]
    AssetKey(String),

    /// Indicates an [`InstrumentNameExchange`] was encountered that was no indexed, so does
    /// not have a corresponding [`InstrumentIndex`].
    #[error("InstrumentKey: {0}")]
    InstrumentKey(String),
}

#[cfg(test)]
#[allow(clippy::unwrap_used)] // Test code: panics on bad input are acceptable
mod tests {
    use super::*;
    use rust_decimal_macros::dec;

    #[test]
    fn a_rate_limit_carries_and_shows_the_venues_wait() {
        let hinted: UnindexedApiError = ApiError::rate_limited(Some(Duration::from_secs(7)));
        assert_eq!(hinted.retry_after(), Some(Duration::from_secs(7)));
        assert_eq!(hinted.to_string(), "rate limit exceeded; retry after 7s");
        assert!(UnindexedClientError::Api(hinted.clone()).is_transient());
        assert!(UnindexedOrderError::Rejected(hinted).is_transient());

        let unhinted: UnindexedApiError = ApiError::rate_limited(None);
        assert_eq!(unhinted.retry_after(), None);
        assert_eq!(unhinted.to_string(), "rate limit exceeded");

        let other: UnindexedApiError = ApiError::Unauthenticated("bad key".to_string());
        assert_eq!(other.retry_after(), None);
    }

    #[test]
    fn a_rate_limit_round_trips_through_serde() {
        for retry_after in [None, Some(Duration::from_millis(7_250))] {
            let error: UnindexedApiError = ApiError::rate_limited(retry_after);
            let json = serde_json::to_string(&error).unwrap();
            assert_eq!(
                serde_json::from_str::<UnindexedApiError>(&json).unwrap(),
                error,
                "{json}"
            );
        }
    }

    #[test]
    fn test_connectivity_error_is_transient() {
        assert!(ConnectivityError::Timeout.is_transient());
        assert!(ConnectivityError::Socket("connection refused".into()).is_transient());
        assert!(ConnectivityError::ExchangeOffline(ExchangeId::BinanceSpot).is_transient());
    }

    #[test]
    fn test_client_error_is_transient_connectivity() {
        let err: ClientError = ClientError::Connectivity(ConnectivityError::Timeout);
        assert!(err.is_transient());

        let err: ClientError = ClientError::Connectivity(ConnectivityError::Socket("err".into()));
        assert!(err.is_transient());
    }

    #[test]
    fn test_client_error_is_transient_rate_limit() {
        let err: ClientError = ClientError::Api(ApiError::rate_limited(None));
        assert!(err.is_transient());
    }

    #[test]
    fn test_client_error_not_transient_api_errors() {
        let err: ClientError =
            ClientError::Api(ApiError::AssetInvalid(AssetIndex(0), "bad".into()));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::BalanceInsufficient(
            Some(AssetIndex(0)),
            "low".into(),
        ));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::InstrumentInvalid(
            InstrumentIndex(0),
            "bad".into(),
        ));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::OrderRejected("rejected".into()));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::OrderAlreadyCancelled);
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::OrderAlreadyFullyFilled);
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError =
            ClientError::Api(ApiError::Unauthenticated("invalid signature".into()));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError =
            ClientError::Api(ApiError::RequestRejected("-1127 More than 24 hours".into()));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::Api(ApiError::BorrowRejected(BorrowReject::new(
            BorrowRejectReason::InventoryUnavailable,
            Some("-3045".into()),
            "-3045 The system doesn't have enough asset now.".into(),
        )));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);
    }

    #[test]
    fn borrow_rejected_shows_its_reason_and_code() {
        let coded: UnindexedApiError = ApiError::BorrowRejected(BorrowReject::new(
            BorrowRejectReason::BorrowDisabled,
            Some("40310000".into()),
            "account is not allowed to short".into(),
        ));
        assert_eq!(
            coded.to_string(),
            "borrow rejected: borrow disabled (code 40310000): account is not allowed to short"
        );

        let uncoded: UnindexedApiError = ApiError::BorrowRejected(BorrowReject::new(
            BorrowRejectReason::Other,
            None,
            "no borrow".into(),
        ));
        assert_eq!(uncoded.to_string(), "borrow rejected: other: no borrow");

        let short: UnindexedApiError = ApiError::BorrowRejected(BorrowReject::new(
            BorrowRejectReason::ShortSaleRestricted,
            None,
            "priced at the bid".into(),
        ));
        assert_eq!(
            short.to_string(),
            "borrow rejected: short sale restricted: priced at the bid"
        );
    }

    #[test]
    fn borrow_rejected_shows_what_is_available_only_when_known() {
        let reject = BorrowReject::new(
            BorrowRejectReason::InventoryUnavailable,
            None,
            "too little to lend".into(),
        );
        assert_eq!(reject.available, None);

        let reject = reject.with_available(dec!(2.5));
        assert_eq!(reject.available, Some(dec!(2.5)));
        assert_eq!(
            reject.to_string(),
            "inventory unavailable: too little to lend (2.5 available)"
        );
    }

    #[test]
    fn balance_insufficient_names_its_asset_only_when_known() {
        let named: UnindexedApiError =
            ApiError::BalanceInsufficient(Some(AssetNameExchange::new("BTC")), "low".to_string());
        assert_eq!(named.to_string(), "balance insufficient for asset BTC: low");

        let unnamed: UnindexedApiError = ApiError::BalanceInsufficient(None, "low".to_string());
        assert_eq!(unnamed.to_string(), "balance insufficient: low");
    }

    #[test]
    fn test_client_error_not_transient_task_failed() {
        let err: ClientError = ClientError::TaskFailed("task panicked".into());
        assert!(!err.is_transient());
    }

    #[test]
    fn test_client_error_not_transient_internal() {
        let err: ClientError = ClientError::Internal("unknown error".into());
        assert!(!err.is_transient());
    }

    #[test]
    fn test_client_error_not_transient_truncated() {
        let err: ClientError = ClientError::Truncated { fills_read: 5_000 };
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: ClientError = ClientError::TruncatedSnapshot { limit: 500 };
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);
    }

    #[test]
    fn test_client_error_is_transient_exchange_offline() {
        let err: ClientError =
            ClientError::Connectivity(ConnectivityError::ExchangeOffline(ExchangeId::BinanceSpot));
        assert!(err.is_transient(), "expected transient for {:?}", err);
    }

    #[test]
    fn test_order_error_is_transient_connectivity() {
        let err: UnindexedOrderError = OrderError::Connectivity(ConnectivityError::Timeout);
        assert!(err.is_transient(), "expected transient for {:?}", err);

        let err: UnindexedOrderError =
            OrderError::Connectivity(ConnectivityError::Socket("connection reset".into()));
        assert!(err.is_transient(), "expected transient for {:?}", err);

        let err: UnindexedOrderError =
            OrderError::Connectivity(ConnectivityError::ExchangeOffline(ExchangeId::BinanceSpot));
        assert!(err.is_transient(), "expected transient for {:?}", err);
    }

    #[test]
    fn test_order_error_is_transient_rate_limit() {
        let err: UnindexedOrderError = OrderError::Rejected(ApiError::rate_limited(None));
        assert!(err.is_transient(), "expected transient for {:?}", err);
    }

    #[test]
    fn test_order_error_not_transient_api_errors() {
        let err: UnindexedOrderError =
            OrderError::Rejected(ApiError::OrderRejected("price out of range".into()));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: UnindexedOrderError = OrderError::Rejected(ApiError::OrderAlreadyCancelled);
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: UnindexedOrderError =
            OrderError::Rejected(ApiError::BorrowRejected(BorrowReject::new(
                BorrowRejectReason::NotShortable,
                None,
                "asset XYZ cannot be sold short".into(),
            )));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);

        let err: UnindexedOrderError = OrderError::Rejected(ApiError::BalanceInsufficient(
            Some(AssetNameExchange::from("BTC")),
            "insufficient".into(),
        ));
        assert!(!err.is_transient(), "expected non-transient for {:?}", err);
    }
}