Enum ApiError 

#[non_exhaustive]
pub enum ApiError<AssetKey = AssetIndex, InstrumentKey = InstrumentIndex> {
    AssetInvalid(AssetKey, String),
    InstrumentInvalid(InstrumentKey, String),
    #[non_exhaustive]
    RateLimit {
        retry_after: Option<Duration>,
    },
    CapacityExceeded(String),
    Unauthenticated(String),
    BalanceInsufficient(Option<AssetKey>, String),
    OrderRejected(String),
    OrderAlreadyCancelled,
    OrderAlreadyFullyFilled,
    OrderAlreadyExpired,
    DuplicateClientOrderId(String),
    RequestRejected(String),
    BorrowRejected(BorrowReject),
}

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, which is transient.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

AssetInvalid(AssetKey, String)

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 (from an order request) or RequestRejected (from any other request), holding this error’s own message.

InstrumentInvalid(InstrumentKey, 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 describes.

#[non_exhaustive]

RateLimit

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: from a REST 429’s or 418’s Retry-After, or the time a WebSocket API refusal’s retryAfter names, measured against the local clock. Uncapped, since a ban can last days, so add it to an Instant with checked_add. A request the client held back unsent, because an earlier refusal’s wait had longer left than the client sleeps through, reports the time left.
• 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.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

retry_after: Option<Duration>

CapacityExceeded(String)

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, 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.

Unauthenticated(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.

BalanceInsufficient(Option<AssetKey>, 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.

OrderRejected(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.

OrderAlreadyCancelled

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.

OrderAlreadyFullyFilled

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.

OrderAlreadyExpired

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 because nobody asked for it: a time-in-force such as 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.

DuplicateClientOrderId(String)

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 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.

RequestRejected(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, 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.

BorrowRejected(BorrowReject)

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 so a caller can tell a refused borrow apart from a malformed order, and from 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, for a CFD short its ShortabilityProvider does not allow. Other clients report such refusals as OrderRejected until their venue’s wording is confirmed.

Not transient — the same request fails identically until the venue’s lending changes.

Implementations

impl<AssetKey, InstrumentKey> ApiError<AssetKey, InstrumentKey>

pub fn rate_limited(retry_after: Option<Duration>) -> Self

A RateLimit refusal, with the venue’s minimum wait when it sent one.

pub fn retry_after(&self) -> Option<Duration>

The venue’s minimum wait before a retry: Some only for a RateLimit whose venue sent a hint the client could read.

Trait Implementations

impl<AssetKey: Clone, InstrumentKey: Clone> Clone for ApiError<AssetKey, InstrumentKey>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<AssetKey: Debug, InstrumentKey: Debug> Debug for ApiError<AssetKey, InstrumentKey>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, AssetKey, InstrumentKey> Deserialize<'de> for ApiError<AssetKey, InstrumentKey>

where AssetKey: Deserialize<'de>, InstrumentKey: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<AssetKey, InstrumentKey> Display for ApiError<AssetKey, InstrumentKey>

where AssetKey: Display, InstrumentKey: Display,

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<AssetKey: Eq, InstrumentKey: Eq> Eq for ApiError<AssetKey, InstrumentKey>

impl<AssetKey, InstrumentKey> Error for ApiError<AssetKey, InstrumentKey>

where Self: Debug + Display,

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<AssetKey, InstrumentKey> From<ApiError<AssetKey, InstrumentKey>> for ClientError<AssetKey, InstrumentKey>

fn from(source: ApiError<AssetKey, InstrumentKey>) -> Self

Converts to this type from the input type.

impl<AssetKey, InstrumentKey> From<ApiError<AssetKey, InstrumentKey>> for OrderError<AssetKey, InstrumentKey>

fn from(source: ApiError<AssetKey, InstrumentKey>) -> Self

Converts to this type from the input type.

impl<AssetKey: Hash, InstrumentKey: Hash> Hash for ApiError<AssetKey, InstrumentKey>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<AssetKey: Ord, InstrumentKey: Ord> Ord for ApiError<AssetKey, InstrumentKey>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<AssetKey: PartialEq, InstrumentKey: PartialEq> PartialEq for ApiError<AssetKey, InstrumentKey>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<AssetKey: PartialOrd, InstrumentKey: PartialOrd> PartialOrd for ApiError<AssetKey, InstrumentKey>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<AssetKey, InstrumentKey> Serialize for ApiError<AssetKey, InstrumentKey>

where AssetKey: Serialize, InstrumentKey: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<AssetKey: PartialEq, InstrumentKey: PartialEq> StructuralPartialEq for ApiError<AssetKey, InstrumentKey>