ADR 0021: Report a rejected order in one line and place it once¶
- Status: Accepted
- Date: 2026-11-12
Context¶
An open signal closes the instrument's positions, then places a market
order. Since step 3b
(ADR 0009),
everything the bot can check before the close is checked there: a missing
balance, a quantity that rounds to zero, an unknown symbol. The broker can
still refuse the order itself. By then the close has been carried out.
Below its minimum lot, without enough margin and with the market closed
are the likely causes; which of them TradeLocker answers in the way the
table below calls a rejection was not observed. The only observed fact is
the client's code path.
The tradelocker client (0.56.2, the version the bot pins) reports an order
in four ways:
| What happened | What create_order does |
|---|---|
| The broker created the order | returns its id, an int |
| The broker answered, but with no order id | raises TLAPIOrderException, holding the answer, whose errmsg usually gives the reason |
| The request failed: no connection, a timeout, an error status (400 or above), an answer that is not JSON | raises TLAPIException |
| Netting, which the bot never enables, left nothing to order | returns None |
The client also resends a request whose connection failed. Its retry
wrapper tries up to four times on a requests exception, the order
included. An order whose answer was lost can therefore fill, and the resend
be rejected, for example for the margin the fill used. A rejection does not
prove that the account holds nothing.
Before this step, the use case returned every client exception as a
BrokerFailure, and the signal handler raised its cause in the webhook
thread. A rejected order therefore ended in a traceback in the log, after
Closing: XAUUSD, and no line said what the account held.
The use case also placed the order again, with no pause and no end, for as
long as the broker answered with an id that was falsy. None never comes
back with netting off, so the loop did not run in practice. An order id of
0 would have run it, placing the same order again and again while holding
the lock every other signal waits for.
Decision¶
A rejection is an answer, so it becomes its own outcome, OrderRejected,
next to BrokerFailure in the ports. The order is placed once, and the
rejection is reported with the positions the broker lists afterwards.
flowchart TD
UC["ExecuteSignal: positions closed,<br/>none left on the instrument"] --> P["Broker.place_market_order, once"]
P --> CL["client create_order"]
CL -- "order id" --> OK["Ok(id)"]
CL -- "TLAPIOrderException:<br/>answered, no order id" --> RJ["Err(OrderRejected(errmsg,<br/>else the whole answer))"]
CL -- "None: no order created" --> RJ
CL -- "any other exception:<br/>no answer" --> BF["Err(BrokerFailure(exception))"]
OK --> PLACED["Order placed successfully, ...<br/>Normal: Unlocked"]
RJ --> COUNT["Broker.open_position_count, again"]
COUNT -- "Ok(n)" --> LINE["one red line: Order rejected: ...;<br/>what the broker lists now<br/>Normal: Unlocked, thread ends normally"]
COUNT -- "Err(BrokerFailure)" --> UNKNOWN["the same line: the count got no answer<br/>then the client exception re-raised"]
BF --> RAISE["client exception re-raised<br/>in the thread, as before"]
- The adapter decides what a rejection is.
TradeLockerBrokerreturnsErr(OrderRejected(reason))for aTLAPIOrderExceptionand forNone. Every other exception stays aBrokerFailure. The port now promises an id for everyOk:place_market_order -> Result[int, BrokerFailure | OrderRejected]. - The reason is the broker's
errmsg, else its whole answer.errmsgis used when it is a non-empty string. Otherwise the answer is shown as it is, escaped and cut like any reason: the traceback this replaces printed it, and nothing else logs it, so dropping it would leave the operator no way to find the cause. The exception's own text is not used: it raises aTypeErrorfor an answer that is a bare string. Only the client'sNone, which comes with no answer, gives(no reason given). - The order is placed once. An id of
0is a placed order. - The positions are counted again after the rejection. The close loop ended with none on the instrument, but a resent order may have filled, and a position may have been opened by hand. The operator acts on what the line says, so the line reports this count, not an assumption.
- The use case prints the line, between
Normal: LockedandNormal: Unlocked, through a newOperatorConsole.order_rejected. It belongs to the same sequence asClosing:andOrder placed, and the use case holds the symbol, the side and the count. It then printsNormal: Unlocked, because the handling ended there, and returnsErr(OrderRejected). The handler only ends the thread normally. If the recount gets no answer, the line says so, and the recount'sBrokerFailureis returned and raised like any other, with noNormal: Unlocked. -
The line is red, in one
printwith the colour reset inside, likeSignal rejected::Order rejected: the broker refused to buy XAUUSD ('Not enough margin'); no XAUUSD position is open Order rejected: the broker refused to sell XAUUSD (no reason given); no XAUUSD position is open Order rejected: the broker refused to buy XAUUSD ('Not enough margin'); the broker lists 1 open XAUUSD position, check it in TradeLocker Order rejected: the broker refused to buy XAUUSD ('Not enough margin'); the position count got no answer, check XAUUSD in TradeLockerThe reason comes from the broker, so it is escaped with
repr, like webhook text, and cut after 160 characters, where a payload value is cut after 40: a reason is a sentence, not a field. The symbol is shown as it is, as inClosing:: it is exactly a name the broker lists. - Not "Signal rejected". That line means nothing was closed; here the close was carried out. - The closed position is not reopened. A reopen would be a second order that no alert asked for. It could be rejected for the same reason, and the use case knows only how many rows it closed, not their side or size.
What changes¶
| Order answer | Before | After |
|---|---|---|
| an id | Order placed successfully, order ID: <id>, Normal: Unlocked |
the same |
an id of 0 |
placed again and again, with no pause or end | placed: order ID: 0, Normal: Unlocked |
TLAPIOrderException |
traceback in the webhook thread | positions counted again, one red Order rejected: ... line, Normal: Unlocked; the thread ends normally |
None (unreachable with netting off) |
placed again and again, with no pause or end | the same as a rejection, with (no reason given) |
| any other exception | traceback in the webhook thread | the same |
A rejection costs one more broker call, the recount. The position on the instrument is closed in every row, as before: the close comes first.
The tests changed with it:
- Flipped pins.
test_a_rejected_order_after_the_close_leaves_no_position_and_raises_nothingintest_position_handling.py.test_an_order_is_placed_once_even_when_the_broker_creates_noneintest_call_sequences.py, for a rejection and forNone, with and without a position to close, each ending with the recount.- The operator-line table in
test_call_sequences.py, which pins the exact line followed byNormal: Unlocked.
- Kept raising.
test_raising_paths.pyand the lock-release table now pin an order request that gets no answer as raising the client's own exception type. Theorder placed againrows are gone fromtest_broker_failures.pyand the use case's unit tests. - New pins.
test_a_rejected_order_ends_the_handler_thread_without_an_exception, on the served app.- A row in
test_broker_failures.pyfor the recount failing: the line says the count got no answer, then the client's exception is raised. - Adapter tests that map
TLAPIOrderExceptionandNonetoOrderRejected, take a non-empty stringerrmsgor else the whole answer, and keep an id of0. - Console tests for the exact bytes, the escaping, the cut, and each state: none open, one, several, and a count that got no answer.
- Use-case tests:
- a rejection is reported with a fresh count, with and without a close;
- a position that appeared meanwhile is reported;
- a failed recount is reported and then returned as the failure.
- Mutations. Each of these changes fails at least one test:
- keeping the rejection a
BrokerFailure; - treating every client exception as a rejection;
- letting
Nonethrough as an id; - taking the exception's text as the reason;
- keeping an empty
errmsg; - dropping the answer when it has no
errmsg; - passing the rejection to the refusal line;
- assuming no position instead of counting;
- swallowing a failed recount;
- dropping
Normal: Unlocked; - placing the order a second time;
- reporting an unknown count or one position as none;
- cutting the reason at 40 characters;
- printing it unescaped.
- keeping the rejection a
What this does not cover¶
- An order request that gets no answer still raises. After a timeout
nobody knows whether the order was placed. It stays a traceback until
broker failures are reported in a step of their own. This includes a
rejection the broker might send with an error status: the client wraps
that in the same
TLAPIExceptionas a timeout. Which status TradeLocker uses for a rejection was not observed. - The client's resend is not changed. It is inside the client. The recount makes the line true about the instrument afterwards, but the resend can still place an order twice when an answer is lost. "Placed once" holds for the bot's code, not for the client's resends.
- A rejection in another shape still raises. Only an answer the client
raises
TLAPIOrderExceptionfor is a rejection. A rejection sent with an error status, or adthat is not an object (the client then raises aTypeError), stays aBrokerFailurewith a traceback, since telling it from an outage would mean matching the client's message. - The count is of rows on the instrument. It does not say which side they are or who opened them.
- An order that gets an id but opens no position still prints
Order placed successfullyandNormal: Unlocked. If the broker accepts an order and cancels it afterwards, the account is left without a position and no line says so. Whether TradeLocker does this for any cause was not observed. - The webhook still answers
200before the signal is handled, so the sender never learns of the rejection. That is the next decision on the roadmap. Update: decided in step 6k: the answer acknowledges receipt, not the outcome (ADR 0023). - Nothing outside the log is told. An operator who does not read the log does not see the line.
Consequences¶
- A rejected order no longer ends the handler thread with a traceback. The log says in one line what was refused, why, and what the broker lists on the instrument afterwards.
OperatorConsolegainsorder_rejectedand losesorder_retry, andPrintingConsoleloses its line,Buy order was not successful, trying again....Normal: Unlockednow follows oneErr: a rejected order, whose handling ends normally. A refusal and a broker failure still leave without it (ADR 0006).- Images built before this step still raise on a rejected order; there, read the client's exception message in the traceback for the reason.
Alternatives considered¶
- Reopen the closed position. Rejected: an order nobody signalled, which the broker may refuse for the same reason, from a use case that does not know the closed position's side or size.
- Retry the order a few times with a pause. Rejected: a rejection is an answer. Margin, lot size and market hours do not change within seconds, and every retry holds the lock that later signals wait for.
- Say "no position is open" without counting. Rejected after review: a resent order can fill before the rejection, and the operator would be told the account is flat while a position is open.
- Print the line in the handler, from the returned rejection. Rejected: the handler would need the side from the signal union, which a close signal lacks, and the line would come after the lock's sequence of lines rather than in it.
- Check the broker's minimum lot before the close. It would prevent one cause of rejection, not margin or a closed market, so the line would still be needed. It stays an alternative for later, as ADR 0009 lists it.
- Treat every exception from the order as a rejection. Rejected: after a timeout the order may exist.
- Make it a
Refusal. Rejected: a refusal comes before any close request (ADR 0009) and is reported asSignal rejected:.