Transaction API

Error Codes

Copy page

Response Format

All Transaction 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:

• binanceChainId is blank or not on the supported-chain list
• address is blank or malformed
• Broadcast request is missing both evmTx and solTx (one is required)
• evmTx.gasLimit or evmTx.gasPrice is not a valid numeric string
• limit is outside the range [1, 100]
• Required @RequestParam or @RequestBody field is absent

---

Authentication & Authorization Errors

These codes are enforced by the API Gateway before the request reaches the Transaction 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)

KYT compliance checks are performed before broadcasting a transaction. All four codes may be returned by POST /broadcast-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
40434	KYT verification failed. Transaction involves high-risk address	Final KYT check failed immediately before broadcast; the transaction is blocked

---

Transaction API Business Errors

Chain Support

Code	Message	Cause	Affected Endpoints
40411	This chain is not supported	The supplied binanceChainId is not in the supported-chain whitelist, or the chain has been temporarily disabled via configuration	/gas-price, /gas-limit, /simulate, /broadcast-transaction

Broadcast

Code	Message	Cause	Affected Endpoints
40431	Transaction broadcast failed, please check gas settings and retry	The wallet-direct RPC service rejected the transaction or returned no result. Common sub-causes: gas too low, nonce conflict, RPC node error, or malformed raw transaction bytes	/broadcast-transaction

---

Server Errors

Code	Message	Cause
50000	Internal server error, please retry later	An unexpected server-side error occurred (e.g. null pointer, serialization error, downstream service failure). 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, order service) is unreachable or returned an error. Retry after a short delay

---

Error Code Reference by Endpoint

Endpoint	Possible Error Codes
GET /api/v1/dex/pre-transaction/supported/chain	40001, 50000
GET /api/v1/dex/pre-transaction/gas-price	40001, 40411, 50000
POST /api/v1/dex/pre-transaction/gas-limit	40001, 40411, 50000
POST /api/v1/dex/pre-transaction/simulate	40001, 40411, 50000
POST /api/v1/dex/pre-transaction/broadcast-transaction	40001, 40311, 40312, 40313, 40314, 40411, 40431, 40434, 50000
GET /api/v1/dex/post-transaction/orders	40001, 50000, 50001

---

Troubleshooting Guide

Symptom	Likely Code	Action
Signature mismatch	40102	Verify pre-hash string: 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)
Broadcast rejected	40431	Verify gasLimit and gasPrice are sufficient. Pre-call /gas-price and /gas-limit to get current estimates before broadcasting
KYT high-risk block	40311/40312/40313	The destination address is flagged. Review the address risk profile; transactions cannot proceed for sanctioned addresses
KYT medium-risk prompt	40314	Display a risk warning to the end user and resubmit with the user's explicit confirmation flag
Chain not supported	40411	Call GET /api/v1/dex/pre-transaction/supported/chain to retrieve the current chain whitelist
All retries return 50001	50001	The history or order service is degraded. Check the status page or contact support