Coverage for src/PythonMetaTrader5/domain/errors.py: 100%
54 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
1"""Typed failure vocabulary shared by every layer."""
3from __future__ import annotations
5from dataclasses import dataclass
6from enum import Enum
7from typing import TYPE_CHECKING
9if TYPE_CHECKING:
10 from PythonMetaTrader5.domain.market import TradeReceipt
13class ErrorKind(Enum):
14 """Why a call failed. What to do about each kind is in the user guide."""
16 INVALID_ARGUMENT = "invalid_argument"
17 """An argument MT5 would misread or refuse: checked before sending, or refused by the server."""
18 INVALID_VOLUME = "invalid_volume"
19 """The volume is outside the symbol's min/max, off its step, or above the position's."""
20 INVALID_PRICE = "invalid_price"
21 """The price is invalid, e.g. a limit on the wrong side of the market."""
22 INVALID_STOPS = "invalid_stops"
23 """A stop-loss or take-profit is zero, negative, not finite or refused by the server."""
24 INVALID_FILLING = "invalid_filling"
25 """The server refused the filling mode chosen from the symbol's flags (10030)."""
26 NO_MONEY = "no_money"
27 """Not enough margin."""
28 MARKET_CLOSED = "market_closed"
29 """The market for the symbol is closed."""
30 TRADE_DISABLED = "trade_disabled"
31 """Trading is not allowed now: on the symbol or account, or in this direction."""
32 ALGO_TRADING_DISABLED = "algo_trading_disabled"
33 """Algo Trading is off in the terminal (10027) or forbidden by the server (10026)."""
34 LIMIT_REACHED = "limit_reached"
35 """A broker limit on orders, positions or volume is reached."""
36 PARTIAL_FILL = "partial_fill"
37 """Only part of the volume was executed; the rest is still open or unfilled."""
38 OUTCOME_UNKNOWN = "outcome_unknown"
39 """The request may or may not have reached the server: check positions, never auto-retried."""
40 RETRIES_EXHAUSTED = "retries_exhausted"
41 """Requotes, price changes, no quotes or too many requests outlasted the `RetryPolicy`."""
42 REJECTED = "rejected"
43 """Any other refusal by the server, unknown retcodes included."""
44 SYMBOL_NOT_FOUND = "symbol_not_found"
45 """The terminal does not know the symbol."""
46 NO_PRICE = "no_price"
47 """The symbol has no quote."""
48 TERMINAL_ERROR = "terminal_error"
49 """A terminal call failed before anything reached the trade server."""
50 BROKEN_SYMBOL_DATA = "broken_symbol_data"
51 """The terminal's symbol data cannot price an order (point 0, NaN tick size, step 0).
53 Unlike TERMINAL_ERROR it does not clear on a resend, so it has its own kind:
54 a bot must escalate, not retry.
55 """
56 CONNECTION_FAILED = "connection_failed"
57 """The terminal did not start or the login failed."""
60@dataclass(frozen=True, slots=True)
61class TradeError:
62 """An expected failure: its `ErrorKind`, a message and the broker's answer if any.
64 ``receipt`` is the broker's raw answer when there was one; ``ticket`` names
65 the position or order when the failure concerns one item of a batch.
66 """
68 kind: ErrorKind
69 message: str
70 retcode: int | None = None
71 # Kept so callers (and the 2.x facade) can inspect the broker's raw answer.
72 receipt: TradeReceipt | None = None
73 # Set when the failure concerns one position/order of a batch operation.
74 ticket: int | None = None
76 def __str__(self) -> str:
77 code = f" (retcode {self.retcode})" if self.retcode is not None else ""
78 ticket = f" [ticket {self.ticket}]" if self.ticket is not None else ""
79 return f"{self.kind.value}: {self.message}{code}{ticket}"