Error Codes

Copy page

Response Format

Business responses return HTTP 200 with the result carried in the code field of the body:

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

A non-zero code always indicates a business error; check msg for a human-readable description. Note that gateway-layer errors are not returned as HTTP 200 — authentication failures return 401, and rate-limit violations return 429 (see Authentication). Handle both the HTTP status and the body code.

---

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:

• addresses is blank or empty in POST /api/v1/defi/data/position/list
• defiProtocolId is blank in POST /api/v1/defi/data/protocol/detail
• investmentId is blank in POST /api/v1/defi/data/investment/detail
• investType is blank in POST /api/v1/defi/data/investment/list
• page or size is out of valid range
• Required field is absent from the request body

---

Authentication & Authorization Errors

These codes are enforced by the API Gateway before the request reaches the DeFi 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. Reduce the request frequency and retry

---

Compliance Errors

These codes are enforced by the API Gateway or the compliance layer before / during the build.

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
40304	Service not available due to compliance restriction	The request is blocked by a compliance rule not covered by a more specific code above

With the exception of POST /data/position/list, the DeFi data and transaction endpoints are subject to geo-restriction — clients from restricted regions cannot call them.

KYT (Know Your Transaction)

Before building a transaction, the service screens the address and the action through KYT. The build endpoints carry the KYT business type (ENTER for deposit / lp-add, EXIT for redeem / lp-remove / claim). A failed check is returned as 40434; the 40311–40314 codes below are the shared KYT error-code range registered by the platform for reference.

Code	Message	Cause
40434	KYT verification failed	The address or fund-flow risk exceeds the threshold for the action's KYT business type; the build is blocked
40311	Transaction rejected due to high-risk address	The counterparty address has a risk score ≥ 70; the 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; registered for reference only — DeFi build endpoints do not return this code in the current release

---

DeFi Data Query Errors

These codes are returned by the data-query endpoints (protocol/detail, investment/detail).

Code	Message	Cause
40470	Requested DeFi resource not found. Check defiProtocolId / investmentId	The defiProtocolId / investmentId does not exist, is invalid, or has been delisted. Verify the ID against protocol/list / investment/list

---

DeFi Transaction Build Errors

When a transaction build fails, the service returns one of the business codes below identifying the failure class; 40459 is a catch-all returned when the failure does not match a more specific code. DeFi transaction codes occupy two ranges: 40450–40460 (build-phase classification) and 40480–40485 (balance / availability / RPC / internal / preview-revert). The 40480–40494 range is reserved for future DeFi transaction codes — it does not collide with the DEX Swap range 40461–40469.

• msg carries a human-readable reason for the specific failure. Its wording may change between releases, so branch your control flow on code, not on msg — treat msg as an opaque string.
• When no specific reason is available, msg falls back to the code's default text.
• Compliance / KYT failures are returned before the build runs, using 40434 (see Compliance Errors above).
• 40484 / 40485 are returned only when the request sets simulate=true and the simulated transaction reverts. With simulate unset / false the preview is not produced, so these codes are never returned. See the "Preview revert" note below the table.

Code	Message	Cause	Typical scenarios
40450	Chain is not supported for DeFi	The chain of the investment is not supported for DeFi actions.	Calling build for a chain outside the supported set
40451	Investment is invalid or not registered	The investmentId is unknown or not registered.	Unknown / malformed investmentId
40452	Investment is delisted, action not allowed	The investment has been delisted or is not investable (display-only protocols such as Nest / Unitas return investable=false) and no longer accepts supply / lp-add / redeem.	Supplying into a delisted investment, or building a transaction against a display-only (non-investable) investment whose position exists in the list but cannot be traded
40453	Invalid request parameters	A request parameter is invalid — bad field format, value out of range, or missing required field, or an investment type / action mismatch. Read msg for the specific reason.	Malformed field, value out of range, missing required field, tickLower/tickUpper not aligned to tickSpacing, lp-add tick-range group missing, calling lp-add / lp-remove on a non-LP (Earn) investment
40454	Claim parameters do not match claim type	The supplied fields do not match the claimType.	claimType without its required companion fields
40455	Health factor below threshold, action rejected	The action would drop the lending health factor below the protocol threshold.	Deposit / borrow that would breach the health-factor limit
40456	Position not found or not owned by wallet	The referenced NFT / position does not exist or is not owned by the wallet.	lp-remove / claim LP_FEE on a position the wallet doesn't own
40457	No remaining liquidity to remove	The LP position has no remaining liquidity.	lp-remove on an emptied position
40458	Auto-swap (zap) failed, cannot build LP tx	The automatic swap required to pair one side of an LP add failed.	lp-add where one side must be swapped and the swap fails
40459	DeFi transaction build failed	The build failed for a reason not covered by a more specific code. Read msg for the detail.	Catch-all build failure
40460	Transaction simulation failed	The simulated transaction reverted during estimation.	The would-be transaction reverts under simulation
40480	Insufficient balance for this transaction	The wallet balance is insufficient for the supplied / approved amount. Not returned in this release — an insufficient balance surfaces only when simulate=true. A preview revert caused by it is mapped to a 40484 / 40485 code (see the "Preview revert" note below); a structured 40480 is reserved for a follow-up release.	Wallet lacks the token amount being supplied
40481	DeFi action is temporarily unavailable	The action is not available in the current configuration.	Action disabled in the current release
40482	Blockchain RPC error, please retry	A blockchain node error occurred; the request can be retried.	Node unreachable / timed out; retryable
40483	DeFi service internal error	An internal service error occurred. If it persists, contact support with the request timestamp.	Unexpected internal failure
40484	Transaction reverted during simulation	A preview simulation (simulate=true) reverted, but the errorMessage did not match any configured revert-substring mapping. Returned only when simulate=true. Read msg for the original revert reason.	Any preview revert whose message is not classified below
40485	Redeem amount exceeds your current position	A preview simulation (simulate=true) reverted because the redeem amount exceeds the wallet's current position. Returned only when simulate=true.	redeem with simulate=true reverting with Redeem amount exceeds your current position.

40459 is a catch-all for build failures not covered by a more specific code (e.g. investmentId ... is not a LP investment, amount X is less than minimum Y). Parameter-shape errors — bad field format, value out of range, missing required field, tick not aligned to tickSpacing — are returned as 40453, not 40459. For both, read msg for the specific reason; the examples above are representative, not exhaustive.

Preview revert (simulate=true only) — When simulate=true and the simulated transaction reverts, the service maps the preview errorMessage to a stable error code instead of returning a soft 200 with preview.success=false. Mapping is substring containment (errorMessage contains a configured substring) and is server-side configurable, so new revert signatures can be classified without a release. The default classifies "Redeem amount exceeds your current position." as 40485; a revert whose errorMessage matches no configured substring falls back to 40484. Reverts are surfaced this way only when simulate=true; without simulation the preview is not produced and these codes are not returned. msg always carries the original revert reason.

---

Server Errors

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

---

Error Code Reference by Endpoint

Endpoint	Possible Error Codes
POST /api/v1/defi/data/position/list	40001, 50000, 50001
POST /api/v1/defi/data/protocol/list	40001, 40301–40304, 50000, 50001
POST /api/v1/defi/data/protocol/detail	40001, 40301–40304, 40470, 50000, 50001
POST /api/v1/defi/data/investment/list	40001, 40301–40304, 50000, 50001
POST /api/v1/defi/data/investment/detail	40001, 40301–40304, 40470, 50000, 50001
POST /api/v1/defi/transaction/deposit	40001, 40301–40304, 40434, 40450–40460, 40480–40485, 50000
POST /api/v1/defi/transaction/redeem	40001, 40301–40304, 40434, 40450–40460, 40480–40485, 50000
POST /api/v1/defi/transaction/lp-add	40001, 40301–40304, 40434, 40450–40460, 40480–40485, 50000
POST /api/v1/defi/transaction/lp-add/calculate	40001, 40301–40304, 40450–40460, 40480–40483, 50000
POST /api/v1/defi/transaction/lp-remove	40001, 40301–40304, 40434, 40450–40460, 40480–40485, 50000
POST /api/v1/defi/transaction/claim	40001, 40301–40304, 40434, 40450–40460, 40480–40485, 50000

/lp-add/calculate is a pure computation endpoint — it does not broadcast, so it does not surface the KYT 40434 code that the on-chain build endpoints do. It also does not run a preview simulation, so 40484 / 40485 never apply.

---

Troubleshooting Guide

Symptom	Likely Code	Action
Signature mismatch	40102	Verify pre-hash string: timestamp + METHOD + requestPath + body. Ensure requestPath includes /build and the raw body 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).
Build rejected with a readable reason	40450–40460, 40480–40485	Read the code to pick the recovery path (e.g. 40460 simulation failed → check the action reverts; 40482 RPC error → retry). 40459 is the catch-all — read msg for the specific reason. Insufficient balance is not returned as 40480 this release — set simulate=true; a balance-related revert is mapped to 40484 / 40485 (see below).
Preview reverts with simulate=true	40484, 40485	The simulated transaction reverted. 40485 = redeem amount exceeds your position (lower the amount or use a smaller ratio); 40484 = any other revert — read msg for the original revert reason. Only returned when simulate=true. New revert signatures can be classified via the server-side revert-message mapping.
claim rejected for field mismatch	40454	Provide the fields required by claimType (LP_FEE → investmentId + nftId; REWARD_PROTOCOL → defiProtocolId + binanceChainId; REDEMPTION → redemptionId).
Investment not found / delisted	40451 / 40452	investmentId is unknown or the investment is delisted for this action. Re-fetch via /data/investment/list.
LP remove on a position with no liquidity	40457	The position has no remaining liquidity; nothing to remove.
Health factor blocked on deposit	40455	The deposit / borrow would drop the health factor below the protocol threshold; reduce the amount.
Address blocked by compliance	40434	The address or fund-flow failed KYT and the build is blocked.
Missing addresses	40001	Ensure addresses array is non-empty in position/list.
All retries return 50001	50001	The upstream DeFi data service is degraded. Check the status page or contact support.