Copy page

Deep Dives

Deep Dive — Request Validation

For state-changing operations, the SDK validates request bodies against the documented shape before signing or sending them. A malformed request fails fast with a typed ValidationError and never hits the network.

Why validate client-side

Authenticated mutations are signed with your nonce and secret. Sending a request the server will reject wastes a nonce and a round trip, and the resulting server error is often less specific than a local check. Validating first means:

• Bad requests fail before authentication — no wasted nonce.
• The error names the exact field and rule that failed.
• You catch mistakes in development, not from a production 400.

ValidationError

Code
import { ValidationError } from "gemini-markets/server";

try {
  await client.trading.createNewOrder({
    symbol: "BTCUSD",
    amount: "not-a-number", // invalid decimal
    price: "50000",
    side: "buy",
    type: "exchange limit",
  });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.operation); // "trading.createNewOrder"
    console.log(err.field);     // "amount"
    console.log(err.rule);      // "format"
    console.log(err.message);   // "amount must be a quoted decimal string"
  }
}

ValidationError extends SdkError and carries three fields for programmatic handling:

Field	Meaning
operation	The operation that failed (e.g. "trading.createNewOrder")
field	The offending field name
rule	The rule that failed ("required", "type", etc.)

Validated operations

Validation covers state-changing operations across trading, prediction markets, clearing, and account services:

Trading — createNewOrder, cancelOrder, cancelAllActiveOrders, cancelAllSessionOrders, getOrderStatus, wrapOrder

Prediction Markets — placeOrder, placeOrderBatch, cancelOrder, cancelOrderBatch, createCombo

Clearing & Instant — createNewClearingOrder, createNewBrokerOrder, confirmClearingOrder, cancelClearingOrder, executeInstantOrder Account Services — withdrawCryptoFunds, transferBetweenAccounts, stakeCryptoFunds, unstakeCryptoFunds, createNewApprovedAddress, removeApprovedAddress, createNewDepositAddress, createNewAccount, renameAccount, addBank, addBankCAD, revokeOAuthToken

Validation is operation-specific. Most read-only operations pass inputs directly to the server, but some (like trading.getOrderStatus) validate that required identifiers are present and well-formed before sending.

What gets checked

Validators enforce the documented shape of each body: required fields are present, and fields have the correct type and format. Common formats:

Rule	Checks
Decimal	Numeric string like "50000.25" (prices, quantities, amounts)
Integer ID	Digit string like "12345"
UUID	RFC 4122 UUID (clientTransferId on transfers and withdrawals)
Boolean	Actual boolean, not "true"
Required	Field is present and non-null

Validation runs on the caller-supplied body before the SDK adds transport fields (nonce, request) and signs. The check is purely structural — it does not contact the server, so it cannot catch business-rule failures (insufficient funds, unknown symbol); those still surface as ApiError subclasses from the server.

Ordering with terms acceptance

For prediction market order placement, validation runs first, then the SDK checks terms acceptance, then it sends. The sequence:

1. ValidationError if the body shape is wrong.
2. AcceptTermsRequired if terms are not accepted (see Patterns).
3. The signed request is sent.

What's next

• Error Handling — the full error hierarchy
• REST Reference — every operation and its access level