Enum Error 

#[non_exhaustive]
pub enum Error {
    Io(Error),
    ParseInt(ParseIntError),
    FromUtf8(FromUtf8Error),
    ParseTime(Parse),
    Poison(String),
    NotImplemented,
    Parse(usize, String, String),
    ServerVersion(i32, i32, String),
    Simple(String),
    InvalidArgument(String),
    ConnectionFailed,
    ConnectionRejected(String),
    UnsupportedTimeZone(String),
    ConnectionReset,
    Cancelled,
    Shutdown,
    EndOfStream,
    UnexpectedResponse(String),
    UnexpectedWireFormat(String),
    UnexpectedEndOfStream,
    InvalidFrame(String),
    Notice(Notice),
    AlreadySubscribed,
    HistoricalParseError(HistoricalParseError),
    ProtobufDecode(DecodeError),
}

The main error type for IBAPI operations.

This enum is marked #[non_exhaustive] to allow adding new error variants in future versions without breaking compatibility.

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.

Io(Error)

I/O error from network operations.

ParseInt(ParseIntError)

Failed to parse an integer from string.

FromUtf8(FromUtf8Error)

Invalid UTF-8 sequence in response data.

ParseTime(Parse)

Failed to parse time/date string.

Poison(String)

Mutex was poisoned by a panic in another thread.

NotImplemented

Feature or method not yet implemented.

Parse(usize, String, String)

Failed to parse a protocol message. Contains: (field_index, field_value, error_description)

ServerVersion(i32, i32, String)

Server version requirement not met. Contains: (required_version, actual_version, feature_name)

Simple(String)

Generic error with custom message.

InvalidArgument(String)

Invalid argument provided to API method.

ConnectionFailed

Failed to establish connection to TWS/Gateway.

ConnectionRejected(String)

TWS/Gateway accepted the TCP connection but closed before completing the handshake — typically a host allow-list mismatch on the gateway. Payload carries the underlying diagnostic.

UnsupportedTimeZone(String)

IB Gateway sent a timezone name that could not be mapped to an IANA zone.

ConnectionReset

Connection was reset by TWS/Gateway.

Cancelled

Operation was cancelled by user or system.

Shutdown

Client is shutting down.

EndOfStream

Reached end of data stream.

UnexpectedResponse(String)

Received unexpected message type. The string carries the Debug repr of the offending wire envelope for diagnostic logging; the structured payload is no longer exposed (rust-ibapi 3.x retired ResponseMessage from the public surface).

UnexpectedWireFormat(String)

A message arrived in the wrong wire format for the reader handling it — text framing at a proto-only decoder, or proto framing at a text-field accessor. The string carries the Debug repr of the offending envelope.

Deliberately distinct from Error::UnexpectedResponse, which means “not my message type” and is skipped on shared channels. A framing mismatch is not skippable: the message was addressed to this reader and could not be read. At server_versions::PROTOBUF_REST_MESSAGES_3 this is unreachable in production, so receiving it means the gateway broke protocol.

UnexpectedEndOfStream

Stream ended unexpectedly.

InvalidFrame(String)

A frame arrived whose length prefix cannot describe a TWS message: shorter than the 4-byte message id, or larger than the 16 MiB ceiling (0x00FFFFFF) that the official client enforces as Constants.MaxMsgSize.

The length prefix is positional — there is no delimiter or magic value to re-anchor on — so a single bad prefix desynchronizes every subsequent read on that socket. Left unchecked, a garbage length is either a multi-gigabyte allocation or a read that silently consumes (and destroys) every real message until it is satisfied. Both end in permanently mis-framed messages that still decode without error, so this is deliberately raised as a hard framing fault rather than skipped.

Treated as is_connection_lost: reconnecting is the only way to re-anchor the stream.

Notice(Notice)

An IB notice frame (TWS error/warning/system message) received in response to a request. Carries the full typed Notice — code, message, optional timestamp, and advanced-order-reject JSON.

Use Notice::category / Notice::is_order_rejection / Notice::is_warning to classify without string-parsing. Distinct from Error::ConnectionRejected (handshake-time refusal) and the transport variants (Error::Io, Error::ConnectionReset).

AlreadySubscribed

Attempted to create a duplicate subscription.

HistoricalParseError(HistoricalParseError)

Wraps errors parsing historical data parameters.

ProtobufDecode(DecodeError)

Failed to decode a protobuf message.

Implementations

impl Error

pub fn is_connection_lost(&self) -> bool

Returns true if this error means the TWS/Gateway stream is unusable in place and the client should reconnect, rather than retry the in-flight request.

Matches Error::ConnectionReset and connection-kind Error::Io errors (broken pipe, unexpected EOF, connection reset/abort) — recoverable losses where re-establishing the connection is the right response — plus Error::InvalidFrame, where the socket is still open but the framing has desynchronized and only a fresh connection can re-anchor it.

Returns false for failures reconnecting cannot recover, so a read loop can branch on them separately to stop retrying: intentional teardown (Error::Shutdown), handshake refusal (Error::ConnectionRejected), and exhausted reconnection (Error::ConnectionFailed, returned only after the transport already gave up).

Examples

In a subscription read loop, branch on this predicate to decide whether to re-establish the connection or surface a request-level failure:

use ibapi::Error;

fn on_stream_error(err: Error) -> Result<(), Error> {
    if err.is_connection_lost() {
        // tear down and resubscribe, then keep going
        Ok(())
    } else {
        // a request-level failure (or terminal disconnect) — surface it
        Err(err)
    }
}

assert!(on_stream_error(Error::ConnectionReset).is_ok());
assert!(on_stream_error(Error::ConnectionFailed).is_err()); // reconnect exhausted
assert!(on_stream_error(Error::Shutdown).is_err());

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 From<DecodeError> for Error

fn from(source: DecodeError) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<FromUtf8Error> for Error

fn from(source: FromUtf8Error) -> Self

Converts to this type from the input type.

impl From<Parse> for Error

fn from(source: Parse) -> Self

Converts to this type from the input type.

impl From<ParseIntError> for Error

fn from(source: ParseIntError) -> Self

Converts to this type from the input type.

impl<T> From<PoisonError<T>> for Error

fn from(err: PoisonError<T>) -> Error

Converts to this type from the input type.

impl From<ValidationError> for Error

fn from(err: ValidationError) -> Self

Converts to this type from the input type.