Errors - Sophic Engine

When an order request fails, we return an error response with a machine-readable code and a human-readable detail message:

{
  "code": "insufficient_funds",
  "detail": "The account does not have sufficient cash to cover this order."
}

Validation errors

These errors are returned synchronously when you place the order. The order is not created. Get an order quote runs the same checks, so a quote returns the same errors, except for sizing rule violations, which it reports in blockers instead (from API version 2026-10-01).

Code	HTTP Status	Description	What to do
`not_found`	400	The instrument doesn’t exist.	Double-check the instrument ID via the instruments endpoint.
`instrument_not_trading`	400	The instrument isn’t currently tradable (e.g. market is closed or the instrument is suspended).	Retry later, or check the instrument’s status via the catalog.
`instrument_buy_only`	400	The instrument only accepts buy orders, so it can’t be sold right now.	Check the instrument’s `trading_status` via the catalog.
`instrument_sell_only`	400	The instrument only accepts sell orders, so it can’t be bought right now.	Check the instrument’s `trading_status` via the catalog.
`invalid_param`	400	A request parameter is invalid; for example, a negative `cash_amount`, a zero `quantity`, both `cash_amount` and `quantity` sent, or an invalid `order_type`.	Check the request body against the expected schema.
`trading_rule_violated`	400	The order breaks a rule in the instrument’s `trading_configuration`, or its `quantity` isn’t a multiple of `trading_increment`. `context.rule` names the rule, with `context.required` and `context.actual`.	Check the instrument’s sizing rules, or get a quote to see what the order needs.
`instrument_too_close_to_maturity`	400	The instrument matures too soon for a trade placed today to settle.	Choose an instrument with a later maturity.
`currency_not_supported`	400	The instrument can’t be traded in the requested currency.	Check which currencies the instrument supports.
`insufficient_funds`	400	The account doesn’t have enough cash to cover the buy order.	Check the account’s cash balance before placing the order.
`insufficient_units`	400	The account doesn’t hold enough units to sell, including when it holds no position in the instrument. `context.available` gives the units available to sell as a decimal string.	Check the account’s positions before placing the order.

Permission errors

These errors indicate the account or user isn’t allowed to perform the requested action.

Code	HTTP Status	Description	What to do
`buy_order_forbidden`	403	Buy orders aren’t enabled for this account.	Contact support to enable buy orders.
`sell_order_forbidden`	403	Sell orders aren’t enabled for this account.	Contact support to enable sell orders.
`professional_trader_required`	403	This instrument requires the account holder to be classified as a professional trader.	Ensure the account meets the professional trader requirements.

Error response format

All error responses follow the same structure:

{
  "code": "instrument_not_trading",
  "detail": "The instrument is not currently tradable.",
  "docs": "https://docs.engine.usesophic.com/api-reference/errors",
  "context": {
    "instrument_id": "ins_xyz789"
  }
}

Field	Type	Description
`code`	string	A machine-readable error code.
`detail`	string	A human-readable description of the error.
`docs`	string	A URL to documentation about this error code. May be absent.
`context`	object	Extra context about the error (e.g. which parameter failed). May be absent.
`params`	array	A list of parameters that failed validation. Only present for validation errors.