Trading API

Error Codes

Copy page

Response Format

All Trading API responses — including errors — return HTTP 200. The business result is indicated by the code field in the response body.

Code
{
  "code": 0,
  "msg": "success",
  "data": { ... },
  "timestamp": 1718000000000
}

A non-zero code always indicates an error. Check the msg field for a human-readable description.

---

Success

Code	Description
0	Request succeeded

---

Parameter Errors

Code	Message	Cause	Affected Endpoints
40001	Parameter [field] error: <reason>	Request parameter failed validation — field format invalid, value out of range, required parameter missing, or unsupported enum value. The msg field includes the specific field name and reason.	All endpoints

Common 40001 triggers:

• chainId is not a positive integer or not on the supported-chain list
• fromTokenAddress / toTokenAddress is not a valid EVM address or Solana pubkey
• amount is not a positive numeric string
• slippagePercent is not a valid decimal string
• gasLevel is not one of the allowed enum values
• Required @RequestParam is absent from the request
• userWalletAddress is missing when quoting an Ondo (RFQ) token pair

---

Authentication & Authorization Errors

These codes are enforced by the API Gateway before the request reaches the Trading API service.

Code	Message	Cause
40101	Invalid API Key	The X-OC-APIKEY header is missing, malformed, or the key has been deleted / disabled
40102	Signature error	The X-OC-SIGN value does not match the expected HMAC-SHA256 or Ed25519 signature. For /order/submit: the userSignature does not match the userWalletAddress used in /quote — ensure the signing wallet is correct and EIP-712 typed data is signed (not a plain-text signature)
40103	Timestamp expired	The X-OC-TIMESTAMP is outside the allowed recv_window relative to server time (default ±5 000 ms)
40104	Permission denied	The API Key does not have the required permission for this endpoint

---

Rate Limit Errors

Code	Message	Cause
42900	Request rate limit exceeded. Please refer to the API docs and reduce request frequency	Per-IP, per-API-Key, per-user, or per-endpoint rate limit has been reached. Retry after the duration indicated in the Retry-After response header

---

Compliance Errors

IP Compliance

Code	Message	Cause
40301	Service not available in your region	The client IP originates from a sanctioned jurisdiction (e.g. North Korea, Iran, Cuba, Syria, or OFAC-listed territory)
40302	Proxy or VPN detected. Please use direct connection	A high-risk VPN or proxy was detected on the client connection
40303	Unusual IP activity detected. Please contact support	Anomalous IP activity such as frequent location switching or concurrent multi-region access

KYT (Know Your Transaction)

Code	Message	Cause
40311	Transaction rejected due to high-risk address	The counterparty address has a risk score ≥ 70; transaction is blocked outright
40312	Address is on sanctions list	The address matches an OFAC or UN sanctions list entry
40313	Transaction rejected due to risky fund origin	Upstream fund tracing (3–5 hops) links the transaction to a sanctioned address, gambling site, or dark-web entity
40314	Medium-risk address detected. Please confirm to proceed	Risk score is 40–69; the client must display a confirmation prompt and resubmit with the user's explicit acknowledgement

---

Trading API Business Errors

Chain Support

Code	Message	Cause	Affected Endpoints
40411	This chain is not supported	The supplied chainId is not in the supported-chain whitelist, or the chain has been temporarily disabled via configuration	/approve-transaction, /quote, /swap, /history
40412	DEX contract not configured for this chain, please contact administrator	The on-chain approve contract address has not been configured for this chain in the backend. This is an operational configuration issue — contact support	/approve-transaction

Quote

Code	Message	Cause	Affected Endpoints
40401	Quote expired. Please request a new quote	The quoteId was not found in cache — either the 30-second TTL has elapsed since the /quote call or the ID is invalid	/swap
40421	Insufficient liquidity for this trading pair	No active liquidity provider (vendor) is available for the requested chain or token pair at this time	/quote
40441	No valid quote result from any vendor, please retry later	All vendors were contacted but none returned a valid quote (all responses were empty, contained errors, or returned a zero output amount)	/quote
40442	fromTokenAddress and toTokenAddress must be different	fromTokenAddress and toTokenAddress are identical	/quote

Swap

Code	Message	Cause	Affected Endpoints
40461	No valid swap route found, please try other token pair	The route cached for the given quoteId references an unknown or missing vendor — request a fresh quote and retry	/swap
40462	quoteId does not match request parameters	The quoteId exists in cache but one or more parameters differ from those used in the original quote request (chainId, fromTokenAddress, toTokenAddress, or amount)	/swap
40463	Price impact exceeds protection threshold	The vendor-reported price impact exceeds the protection threshold (default 90%). Pass priceImpactProtectionPercent=100 to disable this check	/swap
40464	slippagePercent out of allowed range	slippagePercent is not a valid number, or is outside the allowed range: [0, 100] for EVM chains, [0, 99.9] for Solana	/swap
40465	Vendor swap call failed, please retry later	The vendor failed to build the swap transaction. Common sub-causes: vendor timeout, null response, Gas estimation failure, Solana ALT account resolution error, EVM proxy address not configured, or missing API Key context. Retry after a short delay	/swap

Custom Fee (Add Fee / Referral Fee)

These error codes apply to the custom-fee feature (feePercent + feeSource on /quote; feePercent + fromTokenReferrerWalletAddress / toTokenReferrerWalletAddress on /swap and /quote-and-swap, and the same fee params on /swap-instruction). The feature supports both EVM chains and Solana (CT_501).

Code	Message	Cause	Affected Endpoints
40466	Invalid feePercent. EVM chains allow (0, 5], Solana allows (0, 10]	feePercent is not a valid number, is out of range ((0, 5] for EVM, (0, 10] for Solana), or has more than 2 decimal places (the on-chain parameter precision limit is 2 decimals). Example: "1.326" is rejected. Validated the same way on /quote, /swap, /quote-and-swap, and /swap-instruction.	/quote, /swap, /quote-and-swap, /swap-instruction
40467	Invalid referrer wallet address for the selected chain	fromTokenReferrerWalletAddress or toTokenReferrerWalletAddress does not match the expected address format for the selected chain (EVM: 0x + 40 hex chars; Solana: Base58 pubkey). Applies to /swap, /quote-and-swap, and /swap-instruction (the quote stage does not take a referrer address).	/swap, /quote-and-swap, /swap-instruction
40468	fromTokenReferrerWalletAddress and toTokenReferrerWalletAddress are mutually exclusive, provide only one	Both fromTokenReferrerWalletAddress and toTokenReferrerWalletAddress were supplied. Pick exactly one — fromTokenReferrerWalletAddress ⇒ fee deducted from the sell token (FROM_TOKEN), toTokenReferrerWalletAddress ⇒ fee deducted from the buy-token output (TO_TOKEN).	/swap, /quote-and-swap, /swap-instruction
40469	Referrer wallet address is not activated on Solana, please fund it with some SOL first	Solana only. The referrer wallet address has no SOL balance (not activated), so the on-chain fee token account (ATA) cannot be created. Fund the referrer address with a small amount of SOL first, then retry.	/swap, /quote-and-swap, /swap-instruction
40470	Tax token cannot configure referral fee on the same side	Solana only. The token on the same side as the fee direction is a tax token (has buyTax > 0 or sellTax > 0), and stacking a same-side fee on top of the on-chain tax transfer would break fee-account accounting. Use the opposite fee direction (e.g. TO_TOKEN when the sell token is the tax token) or remove the fee.	/quote, /swap, /quote-and-swap, /swap-instruction

Note: On /swap, the fee direction (implied by which referrer address is supplied) and the feePercent value must match the ones locked in the /quote cache for the same quoteId; a mismatch returns SWAP_QUOTE_MISMATCH (40462). The /quote-and-swap Flash API has no prior quote, so the fee is fully determined by the request itself.

Gas

Code	Message	Cause	Affected Endpoints
40432	Failed to estimate gas price, please retry later	The gas price service (wallet-direct) returned no data. This is usually a transient issue — retry after a few seconds	/approve-transaction

RFQ Orders (Equity Token Errors)

These error codes apply specifically to equity / RWA token trading (Ondo and BStock tokens).

Code	Message	Cause	Affected Endpoints
40374	RWA_INSUFFICIENT_LIQUIDITY	The RWA token has no available liquidity from any vendor (LiquidMesh + PcsXRfq all returned no quotes). Common for newly listed or thinly traded equity tokens.	/quote
40365	ONDO_TOKEN_PAIR_NOT_SUPPORTED	Neither side of the token pair is an Ondo token, but Ondo-only mode is enabled (only-ondo-mode=true). Ensure at least one of fromTokenAddress / toTokenAddress is an Ondo token.	/quote
40366	ONDO_MAX_SINGLE_ORDER_LIMIT	The order amount exceeds the maximum single-order limit configured by the market maker for this Ondo token.	/quote
40367	ONDO_MARKET_STATE_NOT_TRADABLE	The Ondo token's underlying asset market is currently closed (e.g. outside US equity market hours or during a halt). Retry when the market reopens.	/quote
40368	ONDO_STABLECOIN_PAIR_INVALID	The Ondo token is paired with a stablecoin that is not on the whitelist (e.g. must pair with USDT on BSC or USDC on ETH). Use a supported stablecoin as the counter token.	/quote
40369	BSTOCK_INVALID_TRADING_TIME	The BStock token's underlying stock exchange is currently closed (outside trading hours). Retry during market hours.	/quote
40370	BSTOCK_INVALID_TRADING_PAIR	The BStock token is paired with a token not on the BStock whitelist. Use a supported counter token.	/quote
40375	ONDO_FROM_USD_AMOUNT_TOO_SMALL	The Ondo quote's fromTokenAmount is below the minimum USD threshold. Increase the order size to meet the minimum (the exact minimum is returned in the msg, e.g. "Minimum order amount is 20 USD.").	/quote
42901	ORDER_SUBMIT_IN_PROGRESS	A concurrent submit with the same requestId is already in progress. Wait for the first request to complete, then retry with the same requestId.	/order/submit

---

Server Errors

Code	Message	Cause
50000	Internal server error, please retry later	An unexpected server-side error occurred (e.g. null pointer, database failure, serialization error). If the problem persists, contact support with the request timestamp
50001	Service temporarily unavailable, please retry later	An upstream dependency (e.g. transaction history service) is unreachable or returned an error. Retry after a short delay

---

Error Code Reference by Endpoint

Endpoint	Possible Error Codes
GET /supported/chain	40001, 50000
GET /approve-transaction	40001, 40411, 40412, 40432, 50000
GET /quote	40001, 40411, 40421, 40441, 40442, 40365, 40366, 40367, 40368, 40369, 40370, 40374, 40375, 40466, 40470, 50000
GET /swap	40001, 40401, 40411, 40461, 40462, 40463, 40464, 40465, 40466, 40467, 40468, 40469, 40470, 50000
GET /quote-and-swap	40001, 40411, 40463, 40464, 40465, 40466, 40467, 40468, 40469, 40470, 50000
GET /swap-instruction	40001, 40411, 40463, 40464, 40465, 40466, 40467, 40468, 40469, 40470, 50000
GET /history	40001, 40411, 50001, 50000
POST /order/submit	40001, 40101, 40102, 40401, 42901, 50000
GET /order/{orderId}	40001, 40101, 50000

---

Troubleshooting Guide

Symptom	Likely Code	Action
Signature mismatch (API auth)	40102	Verify pre-hash string construction: timestamp + METHOD + requestPath + body. Ensure requestPath includes the raw query string exactly as sent
RFQ signature rejected	40102	Ensure userSignature is an EIP-712 signature (eth_signTypedData_v4) of rfq.typedDataToSign, signed by the wallet that matches userWalletAddress
Timestamp drift	40103	Sync your system clock with an NTP server. Use X-OC-RECV-WINDOW to extend tolerance (max 60 000 ms)
Quote works but swap fails	40401	Re-call /quote immediately before /swap. The quote TTL is 30 seconds
Swap returns param mismatch	40462	Ensure chainId, fromTokenAddress, toTokenAddress, and amount passed to /swap exactly match those used in the /quote call
Custom fee percent rejected	40466	Use a value in the chain-specific range ((0, 5] for EVM, (0, 10] for Solana) with at most 2 decimal places (e.g. "1.5")
Custom fee referrer address rejected	40467	Provide a valid address for the selected chain — EVM (0x + 40 hex chars) or Solana Base58 pubkey — for fromTokenReferrerWalletAddress / toTokenReferrerWalletAddress
Both referrer addresses supplied	40468	fromTokenReferrerWalletAddress and toTokenReferrerWalletAddress are mutually exclusive. Pick exactly one to set the fee deduction direction
Fee direction mismatch on swap	40462	The referrer address passed to /swap must imply the same direction (FROM_TOKEN / TO_TOKEN) that was locked in the /quote cache for that quoteId
High price impact warning	40463	Reduce trade size, or pass priceImpactProtectionPercent=100 to bypass the check (not recommended for large orders)
Chain not supported	40411	Call GET /supported/chain to retrieve the current whitelist before building your request
All retries return 50001	50001	The history service is degraded. Check the status page or contact support
Ondo token quote fails	40367	The underlying asset market is closed. Check US equity market hours and retry when the market reopens
BStock token unavailable	40369	Outside stock exchange trading hours. Retry during market hours
No quotes for RWA token	40374	The token currently has no liquidity from any vendor. Try a different token or retry later
/order/submit concurrent duplicate rejected	42901	Wait for the in-progress request to resolve, then retry with the same requestId