brokapi.errors

Errors of brokapi.

The names and the meaning are those of Error in the Rust library (brokapi_core::Error): one class per variant, and str(error) is the text that Rust prints for the same error. The errors page of the book says what each one means and what to do. error_class answers the one question that matters most: may the call be tried again (RETRYABLE), will it fail again until something changes (FATAL), or is the outcome of a command not known (UNKNOWN).

The one that needs care is Unknown. A command (place, cancel, replace) was sent and nothing says whether the broker did it. Never send it again. Ask the broker with order_state(cid) first.

>>> from brokapi import errors
>>> str(errors.NotReconciled())
'not reconciled: call reconcile() before trading commands'
>>> errors.Unknown().error_class is errors.ErrorClass.UNKNOWN
True
class BrokapiError(builtins.Exception):

Base class of every error that brokapi raises about a broker or a command.

error_class: ClassVar[ErrorClass] = <ErrorClass.FATAL: 'Fatal'>

May the call be tried again: see ErrorClass.

class Config(BrokapiError):

The setup is wrong: a missing token, a bad value, an input that cannot work with this broker.

Nothing was sent. The call fails the same way until the setting is fixed.

Config(message: str)
message
Inherited Members
BrokapiError
error_class
class Degraded(BrokapiError):

The trading gate is closed because the connector lost events it could not afford to lose.

A lossless subscription overflowed (an ~brokapi.Overflow event was sent). Read the event stream to the end, then call reconcile(): a successful one opens the gate again. Nothing was sent.

Inherited Members
BrokapiError
error_class
class ErrorClass(enum.Enum):

The coarse answer to "may I try this call again" (Error::class in Rust).

RETRYABLE = <ErrorClass.RETRYABLE: 'Retryable'>

The call failed for a reason that can pass: the network, a rate limit.

FATAL = <ErrorClass.FATAL: 'Fatal'>

The same call fails again until something else changes: a setup, a refused request, a closed gate.

UNKNOWN = <ErrorClass.UNKNOWN: 'Unknown'>

The outcome of a command is not known. Repeating it could create a second order.

class LogError(BrokapiError):

The event log could not be written or read (LogError of the Rust library).

kind says why: io (the file or the disk failed: check the path and the space), format (a line is not what the format says, the file is damaged or is not a log: line is its number, the header is line 1) or schema (the file was written by a newer version: update the package to read it). A reader never skips a bad line silently: it stops with this error.

LogError( kind: str, message: str, line: int | None = None, found: int | None = None, supported: int | None = None)
kind: str

io, format or schema.

line: int | None

The number of the bad line (from 1), for format.

found: int | None

The format or schema the file declares, for schema.

supported: int | None

The newest this build reads, for schema.

Inherited Members
BrokapiError
error_class
class NotReconciled(BrokapiError):

The trading gate is closed: reconcile() has not run successfully yet.

Call reconcile with your ledger (an empty list if you have none), then repeat the command. Nothing was sent.

Inherited Members
BrokapiError
error_class
class RateLimited(BrokapiError):

A rate limit stopped the call: the local counter of the connector or the broker's own answer.

Wait retry_after, then repeat. A command refused by the local counter was not sent. The library does not wait and repeat for you.

RateLimited(retry_after: datetime.timedelta | float)
error_class = <ErrorClass.RETRYABLE: 'Retryable'>

May the call be tried again: see ErrorClass.

retry_after: datetime.timedelta

How long to wait before the next try. A hint, not a promise that the next call passes.

class Rejected(BrokapiError):

The broker (or the connector, before sending) said no to this request, and nothing was done.

The request is wrong or not allowed: a price outside the band, no money, an unknown order. Change the request. Do not repeat it as it is. code is a short label set by the connector (validation, missing_price, not_found, price_off_step, ...), safe to compare with ==. Do not parse message.

Rejected(code: str, message: str)
code: str

Short label of the reason, set by the connector.

message: str

Explanation for a human, usually the broker's own text.

Inherited Members
BrokapiError
error_class
class ShuttingDown(BrokapiError):

The connector is shutting down and takes no new trading commands.

Final for this client. Orders already at the exchange are not touched by a shutdown. Connect again to trade.

Inherited Members
BrokapiError
error_class
class Transport(BrokapiError):

The network or the broker's endpoint failed in a way that is not an answer (connect, TLS, timeout, a cut stream).

For a reading call, repeat it later. A command that might have reached the broker raises Unknown instead, so this error on a command means the connector has no sign that it did.

Transport(message: str)
error_class = <ErrorClass.RETRYABLE: 'Retryable'>

May the call be tried again: see ErrorClass.

message
class Unknown(BrokapiError):

A command was sent and nothing says whether the broker did it: a timeout, a cut connection, an HTTP 5xx.

The order may exist, may be cancelled, or may never have arrived. The library never repeats the command and neither should you:

  1. Do not send the command again.
  2. Ask the broker: order_state(cid), active_orders() or the executions.
  3. Only when the broker has no such order, place a new one under a NEW cid.
error_class = <ErrorClass.UNKNOWN: 'Unknown'>

May the call be tried again: see ErrorClass.

class Unsupported(BrokapiError):

This connector or this broker does not have the capability, so the call was not made.

Raised at once, without a network call. capability is a short name of what is missing. The library does not emulate a missing stream by polling. client.caps says in advance what a connector can do.

Unsupported(capability: str)
capability: str

Short name of the missing capability, safe to compare with ==.

Inherited Members
BrokapiError
error_class