Errors & Reason Codes

Order endpoints explain the outcome in the response body, so check the body as well as the HTTP status. Reason codes are stable: map them to client-facing messages rather than parsing message.

Creating Orders

Applies to POST /primary/v1/omnibus/order and to the model order calls POST /primary/v1/omnibus/model-order, POST /primary/v1/omnibus/model-order/investor-orders and POST /primary/v1/omnibus/model-order/complete. Apart from request-validation 400s, the body is the create response: id, externalId, status, statusReasonCode, message and submittedAtUtc. Model order responses also carry receivedOrderCount and, when one line caused the refusal, rejectedOrderReferenceId.

HTTP	Meaning
`200`	Model orders: `investor-orders` added the batch. The model order is still `Draft`
`201`	Processed. Check `status`: most orders are `Received` (or `PendingActions`), but some are stored as `Rejected` (see below). A new model order is `Draft`
`202`	Model orders: `complete` accepted the model order, which is now `Processing`. Its outcome is sent by webhook (see below)
`400`	The request failed validation. The body is a validation problem with an `errors` map keyed by field, including two lines in one batch that share an `accountId` or `referenceId`. Model orders also return `400` for the custodian checks in the table below, `InvalidOrderAmount`, `BelowMinimumInvestment` and `OrdersExceeded` (more than 10,000 lines)
`403`	`AccountAccreditationInvalid`: the account's accreditation is missing, more than 12 months old or `NOT_APPLICABLE`
`404`	The account, investor, financial advisor, share class or custodian was not found (`AccountNotFound`, `InvestorNotFound`, `FinancialAdvisorNotFound` and so on), or the `modelOrderId` sent to `investor-orders` or `complete` was not found
`409`	`DuplicateReferenceId`: the `referenceId` has already been used. `AccountInvalid`: the account is closed. Model orders only: `DuplicateOrderReferenceId` (a line's `referenceId` has already been used, or is already on an open model order), `DuplicateAccountId` (the account was added in an earlier batch), `RequiredOrderActionsIncomplete` (an account has open order actions), `OmnibusAccountNotFound`, the sell and limit checks in the table below, `ModelOrderNotDraft` (lines added to, or `complete` called for, a model order that is no longer `Draft`), `OrderCountMismatch` (`totalOrderCount` doesn't match the lines received) and `ModelOrderModifiedConcurrently` (two requests changed the draft at once; retry)
`503`	`SettlementPublishFailed`: Monark could not hand the order to settlement, and it is saved as `Failed`. Look it up by `referenceId`, then resubmit with a new `referenceId`. For a model order this happens after `complete`, so it ends `Failed` with an `OmnibusModelOrderFailed` webhook instead

Some orders rejected by Monark's checks are still stored, and return 201 with a status of Rejected and a statusReasonCode. They do not send a webhook.

Model orders are checked when you create the draft and as each batch is added. A refused batch adds nothing, and the model order stays Draft: the Model orders column below shows those responses. Every line is checked again after complete, because holdings, limits and order actions can change in between. A failure at that point rejects the whole model order: it is stored as Rejected with no individual orders, and OmnibusModelOrderRejected names the check in statusReasonCode and, when one line caused it, the line in rejectedOrderReferenceId.

`statusReasonCode`	Individual orders	Model orders	Meaning
`InsufficientSellableShares`	`201` Rejected	`409`, not stored	A sell exceeds the account's settled shares for that election, less shares in its open sells
`SellHoldingsUnavailable`	`201` Rejected	`409`, not stored	Monark couldn't verify the account's holdings. Retry later
`MaxOrderNotionalExceeded`, `MaxDailyNotionalExceeded`, `MaxOrderQuantityExceeded`, `MaxDailyQuantityExceeded`	`201` Rejected	`409`, not stored	The order exceeds a custodian's per-order or daily limit
`FinancialInstitutionFundAccessDenied`	`201` Rejected	`400`, not stored	The custodian is not enabled for the fund
`InvestorFinancialInstitutionMismatch`, `FinancialAdvisorInvalid`	`201` Rejected	`400`, not stored	The account's owner or the advisor is at a different custodian from the order
`InvestorFinancialInstitutionMissing`	`201` Rejected	`400`, not stored	The account's owner has no custodian
`OmnibusAccountNotFound`	`201` Rejected	`409`, not stored	There is no omnibus account yet for the custodian, share class and distribution election
`OrderNettingCapabilityMissing`	`201` Rejected	`409`, not stored	The order was routed to the netting queue, but Monark has not enabled netting for this custodian, fund and share class. It is not sent to the TA instead
`OrderNettingFinancialInstitutionMissing`	`201` Rejected	—	The order was routed to the netting queue, but the account's owner has no custodian
`InvalidNettingInstructions`	`201` Rejected	`400`, not stored	The netting deadline can't be set, for example a `nettingTifDate` in the past, no business day left in the `nettingTif` period, or no netting schedule for the share class. A model order is checked again when it is completed, and is then stored as `Rejected`

Netting fields sent with a TransferAgent route, a nettingTif other than Cutoff without unnettedOrderRoute: Cancel, a nettingTifDate without Custom, and routeInstruction: CrossCustodianNetting all fail validation with 400.

Cancelling & Amending

Call	Accepted	Refused
`POST /primary/v1/omnibus/order/{id}/cancel`, `POST /primary/v1/omnibus/model-order/cancel`	`200` with `status` of `Accepted` or `Pending`	`409` when the order can no longer be cancelled
`PUT /primary/v1/omnibus/order/{id}`	`202` with `status` of `Accepted` or `Pending`	`409` when the order can no longer be changed

Cancellations and amendments are possible until Monark's cutoff. Only individual orders can be amended. Orders routed to the netting queue can't be cancelled or amended unless they are still PendingActions; most go straight to the netting queue and never are. Cancelling an order or model order returns 409 with OrderNettingCancellationUnsupported, and amending returns 409 with OrderNettingUpdateUnsupported. Model order lines can't be cancelled or amended on their own (ModelOrderChildNotDirectlyMutable), so cancel the whole model order instead. Refusals carry a reasonCode and message, and don't send a webhook. A Pending request can still be refused, and resolves later through the Cancelled, CancelRejected, Updated or UpdateRejected webhook events.

After Submission

An accepted order can still end as Rejected or Failed. Rejected with Settlement:TaRejected means the TA refused the trade. Failed means an operational problem, such as Settlement:ConfirmationTimeout when the TA's confirmation does not arrive in time. A buy the custodian does not fund will not settle. A netting order can also be rejected after submission, before it is accepted, with an Execution: code. For example, Execution:LastNettingDateInPast means its netting deadline passed while it waited for order actions. And a netting order with unnettedOrderRoute: Cancel that reaches its deadline ends Settled or Cancelled with Execution:Expired. The order's statusReasonCode and rejectedStatusReasonMessage explain what happened.

Other Endpoints

HTTP	Meaning
`400`	Invalid request. Validation failures list each field in an `errors` map; other errors explain in `detail`
`401`	Missing or invalid API key
`403`	Your API key is not permitted to perform this action
`404`	Not found, or not visible to your platform
`409`	Conflicts with the current state of the record
`503`	Temporarily unavailable. Retry with backoff