Coverage for src/PythonMetaTrader5/domain/retcodes.py: 100%
22 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"""What a MetaTrader 5 trade-server return code means for the caller.
3Codes are integers from the MQL5 "Trade Server Return Codes" table; they are
4duplicated here so the domain never imports the MetaTrader5 package.
5"""
7from __future__ import annotations
9from enum import Enum
11from PythonMetaTrader5.domain.errors import ErrorKind, TradeError
14class Outcome(Enum):
15 SUCCESS = "success"
16 RETRY = "retry"
17 FAIL = "fail"
20# PLACED is how the server confirms a pending order; 2.x only accepted DONE and
21# therefore re-sent limit orders that had already been placed.
22PLACED = 10008
23DONE = 10009
24DONE_PARTIAL = 10010
25_SUCCESS = frozenset({PLACED, DONE, DONE_PARTIAL})
27# Only codes where the server provably did NOT execute the request. TIMEOUT and
28# CONNECTION are deliberately absent: the order may already be live, and an
29# automatic retry would open a second position.
30_RETRY = frozenset({10004, 10020, 10021, 10024})
32_FAILURES: dict[int, tuple[ErrorKind, str]] = {
33 10004: (ErrorKind.REJECTED, "requote"),
34 10006: (ErrorKind.REJECTED, "request rejected by the server"),
35 10007: (ErrorKind.REJECTED, "request cancelled by the trader"),
36 10011: (ErrorKind.REJECTED, "request processing error"),
37 10012: (ErrorKind.OUTCOME_UNKNOWN, "request timed out; check positions before retrying"),
38 10013: (ErrorKind.INVALID_ARGUMENT, "invalid request"),
39 10014: (ErrorKind.INVALID_VOLUME, "invalid volume"),
40 10015: (ErrorKind.INVALID_PRICE, "invalid price"),
41 10016: (ErrorKind.INVALID_STOPS, "invalid stops; too close to the price or wrong side"),
42 10017: (ErrorKind.TRADE_DISABLED, "trading is disabled"),
43 10018: (ErrorKind.MARKET_CLOSED, "market is closed"),
44 10019: (ErrorKind.NO_MONEY, "not enough money"),
45 10020: (ErrorKind.REJECTED, "prices changed"),
46 10021: (ErrorKind.NO_PRICE, "no quotes to process the request"),
47 10022: (ErrorKind.INVALID_ARGUMENT, "invalid order expiration"),
48 10024: (ErrorKind.REJECTED, "too many requests"),
49 10026: (ErrorKind.ALGO_TRADING_DISABLED, "autotrading disabled by the server"),
50 10027: (ErrorKind.ALGO_TRADING_DISABLED, "enable Algo Trading in the MetaTrader 5 terminal"),
51 10028: (ErrorKind.REJECTED, "request locked for processing"),
52 10029: (ErrorKind.REJECTED, "order or position frozen"),
53 10030: (ErrorKind.INVALID_FILLING, "filling mode not supported by the symbol"),
54 10031: (ErrorKind.OUTCOME_UNKNOWN, "no connection to the trade server; check positions"),
55 10032: (ErrorKind.TRADE_DISABLED, "operation allowed only on live accounts"),
56 10033: (ErrorKind.LIMIT_REACHED, "pending orders limit reached"),
57 10034: (ErrorKind.LIMIT_REACHED, "volume limit for the symbol reached"),
58 10035: (ErrorKind.INVALID_ARGUMENT, "invalid or prohibited order type"),
59 10036: (ErrorKind.REJECTED, "position already closed"),
60 10038: (ErrorKind.INVALID_VOLUME, "close volume exceeds position volume"),
61 10039: (ErrorKind.REJECTED, "a close order for this position already exists"),
62 10040: (ErrorKind.LIMIT_REACHED, "open positions limit reached"),
63 10041: (ErrorKind.REJECTED, "pending order activation rejected"),
64 10042: (ErrorKind.TRADE_DISABLED, "only long positions are allowed"),
65 10043: (ErrorKind.TRADE_DISABLED, "only short positions are allowed"),
66 10044: (ErrorKind.TRADE_DISABLED, "only position closing is allowed"),
67 10045: (ErrorKind.REJECTED, "FIFO rule: close older positions first"),
68}
71def classify(retcode: int) -> Outcome:
72 if retcode in _SUCCESS:
73 return Outcome.SUCCESS
74 if retcode in _RETRY:
75 return Outcome.RETRY
76 return Outcome.FAIL
79def error_for(retcode: int) -> TradeError:
80 kind, message = _FAILURES.get(retcode, (ErrorKind.REJECTED, "unrecognised server retcode"))
81 return TradeError(kind, message, retcode=retcode)