Errors

Every error is JSON with an error field, and on most routes that field is a sentence. This page explains the shapes an error takes, the codes a refused request carries, and what each HTTP status means. Use it when you write the error handling for your integration.

{ "error": "clientOrderId required" }

The error text is written for a person reading a log. Show it, log it, and decide what to do from the status and the code. Some routes add fields you should keep, such as code, params, commandId, referenceId or the details of a conflict, because they tell you whether a retry is safe.

Error shapes

Where	Shape	Example
Trading routes	`error` is a sentence, beside a `code` and its `params`	`{ "error": "…", "code": "risk_locked", "params": { "holds": ["risk_uncovered"] } }`
Account-issuing and balance routes	`error` is a sentence, beside a `code` and its `params`	`{ "error": "…", "code": "amount_precision_exceeded", "params": { "currency": "USDC", "decimals": 6 } }`
Venue routes	`error` is the code itself, sometimes with `field` or `params`	`{ "error": "loss_limit_unenforced", "field": "group.risk.dailyLossLimit" }`

Trading refusals

When trdrs refuses a trading request before anything reaches the market, the answer carries the refusal’s code and params. For example, a futures account at Binance held in Hedge Mode is refused like this:

{
  "error": "Binance reports this futures account in Hedge Mode. trdrs trades One-way Mode only; switch the position mode to One-way in Binance to trade here.",
  "code": "hedge_position_mode",
  "params": { "provider": "binance", "instrument": null, "setting": "position_mode", "reported": "hedge", "supported": ["one_way"] }
}

code is one of the codes in the Refusal model of the API reference. They fall into these groups:

Refused by	Codes include
The provider’s account settings	`hedge_position_mode`, `multi_assets_mode`, `portfolio_margin` and the rest of the account-mode codes
The paper book’s product rules and your venue’s conditions	`instrument_not_permitted`, `order_quantity_above_limit`, `entry_halted`, `venue_route_missing` and more
A hold on the account	`risk_locked`, with the holds in `params.holds`
A missing price on an issued account	`market_data_unavailable`, when the only hold is an instrument whose price hasn’t arrived yet
A close-only account	`stage_version_unrecorded`
An account held for reconciliation	`reconciliation_hold`
The live-trading switch	`feature_disabled`
The paper book’s own checks on an issued account	`not_found`, `permission_denied`, `invalid_request`, `version_conflict`, `idempotency_conflict`, `position_mode_unsupported`, `position_not_closable`, `position_revision_stale`, `product_economics_unsupported` and `currency_economics_unsupported`, with no parameters
The engine’s own admission	`outcome_unknown`, `engine_draining`, `engine_overloaded` and the rest

Every account a venue issues is an issued account here. Any other rejection, including the provider’s own, is order_rejected, and its error is the sentence to show. params carries only what your client needs to say the same thing in its own words: a provider’s name, an instrument, a mode or a limit. It never carries a secret, an account number or text a provider sent. Translate a refusal from its code and params, keep error as the English fallback, and show a general message for a code your client doesn’t know, because the list grows.

GET /api/trading/actions answers with the same refusals before an order is sent. Use it to disable what would be refused and say why, while what stays open, such as cancels and flattening under a hold, stays enabled. It’s advisory: the order is judged again when it’s sent.

Account and balance errors

The account-issuing and balance routes refuse these before anything is created or recorded. They aren’t trading refusals and aren’t in the Refusal model.

{
  "error": "amount has more than 2 decimals, the precision of a USDC account; nothing was recorded",
  "code": "amount_precision_exceeded",
  "params": { "currency": "USDC", "decimals": 2 }
}

Code	Status	When	`params`	What to do
`amount_precision_exceeded`	`400`	A credit, debit or adjustment has more decimals than the account’s currency is posted in	`currency`, and `decimals`: 2 for USD; 6 for USDC on an issued account and 2 otherwise; `null` for a currency the paper book holds no money in	Correct the amount and send the same reference again
`balance_refused`	`409`	A debit on an issued account can’t be made. A debit there withdraws free collateral	`reason`: `insufficient_funds` (less free collateral than the amount), `permission_denied` (a hold is on the account) or `invalid_request` (a position can’t be valued right now)	Send the same reference again once the cause clears
`currency_not_issuable`	`400`	An issue names a currency this deployment doesn’t issue: USDC outside the sandbox, or anything but USD and USDC. A batch is refused whole	`currency`, and `environment`: `sandbox` or `production`	Issue in USD, or USDC in the sandbox

The venue routes answer currency_not_issuable and amount_precision_exceeded in their own shape, with the code as error beside the same params. While an account is held for reconciliation, no money moves on it, not even a credit. A balance operation is refused with 423 and reconciliation_hold, and records nothing, until a trdrs operator releases the hold.

Venue configuration errors

The venue routes refuse a configuration they won’t store, with the code as error. Nothing is recorded.

Code	Status	When	What to do
`idempotency_key_required`	`400`	A write has no `Idempotency-Key` header, or one longer than 128 characters	Send a key; see Idempotency
`loss_limit_unenforced`	`400`	A profile, group override, preview or account override states `dailyLossLimit` or `weeklyLossLimit` while an account the venue issued isn’t bound to its published risk policy, such as one held at a provider. Nothing would enforce the limit on that account	Send `null`, or leave the field out of an override
`margin_policy_superseded`	`400`	A profile, group override or preview states a `margin` policy. Margin comes from your published risk policy	Send `margin: null`, or leave it out of an override
`financing_superseded`	`400`	A profile, group override or preview states `financing`. Financing comes from your published risk policy	Leave the field out
`unsupported_value`	`400`	A commission leaves out its `timing`, its `direction` or, per unit, its `unit`. A venue condition’s per-unit `unit` is `quantity`	State the field `field` names
`round_turn_is_both`	`400`	A `round_turn` commission is stated for one direction only. A round turn charges the closing fill for both sides	State it with `direction: "both"`
`entitled_source_unserved`	`400`	An instrument names an `entitlement` whose `pricing.sourceId` isn’t a source trdrs serves from each trader’s own feed (`rithmic` today; see Providers), so no account holding it could be valued. Checked when the instrument is saved and when it’s activated	Use a served source
`risk_policy_owner_conflict`	`409`	The policy id belongs to another venue or to trdrs, or the policy’s authority names another venue	Use your own policy id, with your venue as its authority
`risk_policy_id_reserved`	`409`	The policy id starts `trdrs-`	Choose another id
`risk_policy_version_conflict`	`409`	Other content is sent under a version already stored	Store the change as a new version
`risk_policy_unsourced`	`409`	A version with a figure marked unsourced is published	Source the figure, store a new version and publish that
`risk_policy_posting_mismatch`	`409`	The posting term states a currency at a precision the paper book doesn’t post it at: USD in 2 decimals, USDC and USDT in 6	Correct the posting term
`risk_policy_unchanged`	`409`	The version is already in force	Nothing to do

The fields a venue route refuses are named in field:

{ "error": "margin_policy_superseded", "field": "group.margin" }

A risk policy the venue doesn’t state is 404 not_found, for a read and for a publication alike.

Status codes

Status	Meaning
`400`	The request is malformed: an unparseable timeframe, an unknown `broker` or `account`, an invalid cursor. It always fails closed and never falls back to a default.
`401`	No credential resolved: the key is missing, malformed, expired or revoked, and the origin isn’t registered.
`402`	Challenges only: the program has a non-zero `priceCents` and this deployment collects no fee.
`403`	On a browser request, `origin not allowed`: the origin check in front of the trading and account routes, not a verdict on your key. On the order and reverse routes, `feature_disabled`: live trading is off for this user, and every order on a real provider account is refused, a reducing one included. On a venue route, the key lacks the scope the route needs.
`404`	The resource doesn’t exist or isn’t yours. On `/api/market/symbol-info`, an unknown symbol. On Challenges, also the answer when challenges aren’t enabled for the deployment.
`409`	The request conflicts with what already happened. The `clientOrderId` was already used and the earlier order stands; a saved exit plan was edited since your preview (`exit_plan_conflict`); the position changed under a close (`position_changed`). A hold refused a command that can’t prove it reduces exposure (`risk_locked`), such as a close the provider doesn’t enforce as reduce-only. An earlier command on the account has an unconfirmed outcome (`command_blocked`) or was already settled (`command_settled`). A command used the reserved safety capacity without reducing exposure (`safety_lane_refused`). On Challenges enrollment, an attempt is already in flight.
`413`	The body is too large. Balance operations accept at most 16 KiB. Make the body smaller before you retry.
`415`	The route needs a JSON body with `Content-Type: application/json`.
`422`	The request is well formed but can’t take part yet. On a trading route it’s a refusal with its `code`: the provider, the account’s mode, the paper book or your venue’s conditions refused the order, and nothing was sent. On an issued account whose only hold is an instrument whose price hasn’t arrived yet, an order adding to that instrument alone is `market_data_unavailable` with `params.cause` `mark_missing`. An order adding to any other instrument is still `423` `risk_locked`, and so is every addition while another hold is on the account. An account whose risk decisions haven’t read any price yet can also answer `423` `risk_locked` there, when its terms have an effective window or a day margin.
`423`	The account is held. With `risk_locked`, `params.holds` names the holds: the order route refuses an order that may add exposure and accepts a reduce-only one, while the exits, reverse and replace routes refuse every order. With `reconciliation_hold`, trdrs found the account’s book doesn’t follow from what happened to it: orders that may add exposure, credits, debits and resets are refused until a trdrs operator releases the hold, and nothing on the book is rewritten. With `stage_version_unrecorded`, the account is close-only because its running cycle can’t prove which stage rules judge it, until the version is established or you reset it; `params.reason` and `params.stageId` say why. Cancels and flattens stay available in every case, and so do reductions and closes, except a close the provider doesn’t enforce as reduce-only while `risk_locked` holds.
`429`	You’re rate limited. Wait for `Retry-After`.
`500`	The server couldn’t complete the request. Retry reads with backoff, and never treat missing eligibility data as a pass.
`502`	A read from the provider failed partway through an account snapshot. A partial snapshot is never served, because a half-read account can’t be told apart from a complete picture of an emptier one. Read it again.
`503`	On the trading routes, a refusal before anything was sent carries `Retry-After: 1`: the account’s engine couldn’t be reached (`ownership_unavailable`, `owner_unavailable`), the engine is draining (`engine_draining`) or shedding orders (`engine_overloaded`), the account’s owner couldn’t be confirmed this second (`account_not_owned`, `account_unresolved`), or the account’s holds or the live-trading switch couldn’t be read. The one trading `503` without `Retry-After` is `outcome_unknown`: the order was sent and may be resting at the provider. On the Legacy Partner API balance operation every `503` carries `Retry-After: 1`, `outcome_unknown` included. Elsewhere, an upstream feed is unconfigured or down, or a futures feed is refused with a typed reason.

Handle the statuses that need care

409 means read the response. A duplicate order means your intent already landed; a conflict means your change was refused. Sending the same clientOrderId again keeps answering 409, and sending a new one would place a second order. Read the account stream to see what actually rests.
503 doesn’t prove nothing happened. A trading 503 with Retry-After was refused before it was sent: wait that many seconds and retry with the same clientOrderId. outcome_unknown means the effect may have happened, whatever the headers say: read the account stream, or the balance operation’s receipt by its original reference. Never mint a new id to get past it.
423 means the account is held, not that the request was wrong. Show it to the trader as a risk hold. Retrying in a loop earns the same refusal.
429 tells you how long to wait. Wait for Retry-After rather than retrying at once.

A request with an Origin header must come from a registered origin, even with a valid key attached. Keys and authentication has the rule.

Get started

Using the API

Check your integration

Error shapes

Trading refusals

Account and balance errors

Venue configuration errors

Status codes

Handle the statuses that need care

​Error shapes

​Trading refusals

​Account and balance errors

​Venue configuration errors

​Status codes

​Handle the statuses that need care

Error shapes

Trading refusals

Account and balance errors

Venue configuration errors

Status codes

Handle the statuses that need care