Skip to main content
Error reporting is still in development. Responses today carry a human-readable message and an HTTP statusCode, but not a stable machine-readable error code, and some venue rejections arrive without the venue’s own reason attached (see Reading order rejections). Readable venue errors and a stable error code are planned. Until they ship, branch your logic on statusCode and treat message as text whose wording can change.
Every error response from the API uses one of three JSON shapes. Validation and most client errors follow the standard shape:
Errors that originate at a connected exchange use a slimmer shape, with the venue name prefixed onto the message:
Order-parameter validation failures use a third shape that lists each rejected field:
Each entry’s path names the offending field (["size"], ["price"], ["timeInForce"], ["trigger","price"], and so on). When a value is merely too precise, the message includes the exact normalized value to resubmit — or set normalizeParams: true on the order to have the API round it for you (see Preparing orders). Operations a venue doesn’t offer at all return 400 with "<exchange>: <method> is not supported" — for example { "message": "extended: batchCreateOrders is not supported", "statusCode": 400 }. An API key missing a permission the venue requires is also a 400, raised when you connect the exchange rather than when you trade. The message names what to turn on:
MEXC reports the same way, listing every futures permission the key lacks. Fix the key at the venue and call the connect endpoint again — see Use your own keys. There is no machine-readable error code field today — match on statusCode and, where you need finer detail, the message string.

​
Status codes

A 400 means the order never left VOOI — fix the request and resend. A 503 means the venue saw the order and either refused it or was briefly unreachable. Because those two cases share a status code, confirm whether the order actually landed before retrying (see Reading order rejections): retrying a true rejection is safe, but retrying after an order that silently went through will double-fill.

​
Reading order rejections

When a venue rejects an order, VOOI returns it as a 503. Whether the venue’s own reason reaches you depends on the exchange and on how the venue reported the failure: Because the surfaced reason is venue-dependent and not yet guaranteed, confirm every order’s outcome through order status or the real-time stream rather than trusting the submit response alone. This is the single most reliable way to know whether an order was accepted, across all venues.

​
Common order-preparation failures

Most rejections on order placement trace back to a value the venue couldn’t accept. These are now caught before the order leaves VOOI and returned as readable 400s with the per-field errors array. Each of these is covered in Preparing orders:
  • Below the venue minimum — e.g. a sub-$10 order on Hyperliquid returns Order must have minimum value of $10 on path: ["size"]. See Minimum order size, where reduceOnly waives the check on most venues.
  • Price or size precision mismatch — too many decimals or, on Hyperliquid, too many significant figures. The message includes the normalized value to resubmit. See Price and size precision.
  • Size rounded to zero — a notional too small to represent one lot step. Don’t submit it.
  • timeInForce without a price — send a market order as { asset, exchange, side, size } with no timeInForce.

​
Token errors

Errors specific to creating API tokens — expired signatures, unset public keys, name collisions — are listed with API Tokens.

​
Next steps

Preparing orders

Round and size orders so the venue accepts them

Real-time updates

Confirm fills through the account and order stream