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

---

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
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

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

---

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, 50000
GET /swap	40001, 40401, 40411, 40461, 40462, 40463, 40464, 40465, 50000
GET /history	40001, 40411, 50001, 50000

---

Troubleshooting Guide

Symptom	Likely Code	Action
Signature mismatch	40102	Verify pre-hash string construction: timestamp + METHOD + requestPath + body. Ensure requestPath includes the raw query string exactly as sent
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
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