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

1"""Typed failure vocabulary shared by every layer.""" 

2 

3from __future__ import annotations 

4 

5from dataclasses import dataclass 

6from enum import Enum 

7from typing import TYPE_CHECKING 

8 

9if TYPE_CHECKING: 

10 from PythonMetaTrader5.domain.market import TradeReceipt 

11 

12 

13class ErrorKind(Enum): 

14 """Why a call failed. What to do about each kind is in the user guide.""" 

15 

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

52 

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

58 

59 

60@dataclass(frozen=True, slots=True) 

61class TradeError: 

62 """An expected failure: its `ErrorKind`, a message and the broker's answer if any. 

63 

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

67 

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 

75 

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}"