错误码

Copy page

响应格式

业务响应返回 HTTP 200，结果由响应体中的 code 字段表示：

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

非零 code 表示业务错误，msg 字段为可读描述。注意网关层错误不返回 HTTP 200——鉴权失败返回 401，限流返回 429（见鉴权）。需同时处理 HTTP 状态码与响应体 code。

---

成功

Code	描述
0	请求成功

---

参数错误

Code	Message	原因	受影响接口
40001	Parameter [field] error: <reason>	请求参数校验失败——字段格式非法、值越界、必填参数缺失或枚举值不支持。msg 字段包含具体字段名与原因。	所有接口

常见 40001 触发场景：

• position/list 中 addresses 为空或为空数组
• protocol/detail 中 defiProtocolId 为空
• investment/detail 中 investmentId 为空
• investment/list 中 investType 为空
• page 或 size 越界
• 请求体缺少必填字段

---

鉴权与授权错误

这些错误码由 API 网关在请求到达 DeFi 服务前校验。

Code	Message	原因
40101	Invalid API Key	X-OC-APIKEY 缺失、格式错误，或该 Key 已被删除 / 停用
40102	Signature error	X-OC-SIGN 与期望的 HMAC-SHA256 或 Ed25519 签名不一致
40103	Timestamp expired	X-OC-TIMESTAMP 超出服务端时间 ±recv_window 范围（默认 ±5 000 ms）
40104	Permission denied	该 API Key 无此接口权限

---

频率限制错误

Code	Message	原因
42900	Request rate limit exceeded. Please refer to the API docs and reduce request frequency	已触发按 IP / API Key / 用户 / 接口的频率限制。请降低请求频率后重试

---

合规错误

这些错误码由 API 网关或合规层在构建前 / 构建中校验。

IP 合规

Code	Message	原因
40301	Service not available in your region	客户端 IP 来自受制裁地区（如朝鲜、伊朗、古巴、叙利亚或 OFAC 名单地区）
40302	Proxy or VPN detected. Please use direct connection	检测到高风险 VPN 或代理
40303	Unusual IP activity detected. Please contact support	IP 行为异常，如频繁切换地区或多地区并发访问
40304	Service not available due to compliance restriction	请求被合规规则拦截（未被上方更具体码覆盖的情形）

除 POST /data/position/list 外，DeFi 数据与交易接口均受地理限制——受限地区客户端无法调用。

KYT（Know Your Transaction）

构建交易前，服务会通过 KYT 对地址与操作进行筛查。构建接口携带 KYT 业务类型（deposit / lp-add 为 ENTER，redeem / lp-remove / claim 为 EXIT）。KYT 校验失败时返回 40434；下方 40311–40314 为平台统一登记的共享 KYT 错误码段，仅供参考。

Code	Message	原因
40434	KYT verification failed	地址或资金流风险超过该操作 KYT 业务类型的阈值，构建被拦截
40311	Transaction rejected due to high-risk address	对手方地址风险分 ≥ 70，交易被直接拦截
40312	Address is on sanctions list	地址命中 OFAC 或 UN 制裁名单
40313	Transaction rejected due to risky fund origin	上游资金追踪（3–5 跳）关联到制裁地址、赌博网站或暗网实体
40314	Medium-risk address detected. Please confirm to proceed	风险分 40–69；仅供平台统一登记参考——本期 DeFi 构建接口不返回该码

---

DeFi 数据查询错误

这些错误码由数据查询接口（protocol/detail、investment/detail）返回。

Code	Message	原因
40490	Requested DeFi resource not found. Check defiProtocolId / investmentId	defiProtocolId / investmentId 不存在、无效或已下架。请对照 protocol/list / investment/list 核对 ID。v1.0 对同一情况返回 40470——v1.1 重编号为 40490，请更新按旧码做的分支判断

---

DeFi 交易构建错误

交易构建失败时，服务返回下方业务码标识失败类别；40459 为兜底码，当失败未匹配到更具体的码时返回。DeFi 交易码占两段：40450–40460 （构建阶段分类）与 40480–40485（余额 / 可用性 / RPC / 内部 / 预览 revert）。40480–40489 段预留给后续 DeFi 交易码，40490–40499 段为 DeFi 数据查询码（如上面的 40490）。

• msg 为该次失败的可读原因。文案可能随版本调整，因此按 code 做控制流分支，不要按 msg——msg 为不透明字符串，仅供透传。
• 无具体原因时，msg 回退为该 code 的默认文案。
• 合规 / KYT 失败在构建执行前返回，错误码为 40434（见上文「合规错误」）。
• 40484 / 40485 仅在请求设 simulate=true 且模拟交易 revert 时返回；simulate 未设 / 为 false 时不产生 preview，故不会返回这两个码。详见下表后的「Preview revert」说明。

Code	文案	原因	典型场景
40450	Chain is not supported for DeFi	投资品所在链不支持 DeFi 操作。数据查询接口在不支持链上于参数校验层直接返回 40001；40450 在对支持范围外链的投资品发起构建时返回。	对支持范围外的链调用构建
40451	Investment is invalid or not registered	investmentId 未知或未注册	investmentId 未知 / 格式错误
40452	Investment is delisted, action not allowed	投资品已下架或不可交易（display-only 协议如 Unitas 返回 investable=false），不再接受 supply / lp-add / redeem	对已下架投资品执行存入，或对 display-only（不可交易）投资品（持仓列表里有仓位但不可交易）发起构建
40453	Invalid request parameters	请求参数无效——字段格式错、值越界、必填缺失，或投资品类型与操作不匹配，具体原因见 msg	字段格式错、值越界、必填缺失、tickLower/tickUpper 未对齐 tickSpacing、lp-add 未传 tick 区间、对非 LP（Earn）投资品调 lp-add / lp-remove
40454	Claim parameters do not match claim type	所传字段与 claimType 不匹配	claimType 缺必填配套字段
40455	Health factor below threshold, action rejected	该操作会使借贷健康因子跌破协议阈值	存入 / 借贷会击穿健康因子阈值
40456	Position not found or not owned by wallet	引用的 NFT / 仓位不存在或不属于本钱包	lp-remove / claim LP_FEE 操作非本钱包仓位
40457	No remaining liquidity to remove	LP 仓位已无剩余流动性	对已清空的仓位 lp-remove
40458	Auto-swap (zap) failed, cannot build LP tx	LP 添加中为配对单边而进行的自动兑换失败	lp-add 需自动兑换单边且兑换失败
40459	DeFi transaction build failed	构建失败但未匹配到更具体的码，具体原因见 msg	兜底构建失败
40460	Transaction simulation failed	估算时模拟交易 revert	模拟时交易 revert
40480	Insufficient balance for this transaction	钱包余额不足以支付本次存入 / 授权金额。本期不返回该码——余额不足仅在 simulate=true 时体现，由此引发的 preview revert 会被映射为 40484 / 40485（见下文「Preview revert」说明）；结构化的 40480 留作下期落地。	钱包代币余额少于存入金额
40481	DeFi action is temporarily unavailable	当前配置下该动作不可用	本期禁用的动作
40482	Blockchain RPC error, please retry	区块链节点异常，可重试	节点不可达 / 超时，可重试
40483	DeFi service internal error	服务内部错误，若持续存在请带请求时间戳联系支持	未预期内部错误
40484	Transaction reverted during simulation	预览模拟（simulate=true）revert，但 errorMessage 未命中任何已配置的 revert 子串映射。仅在 simulate=true 时返回，msg 为原始 revert 原因。	任何未归类为下方条目的 preview revert
40485	Redeem amount exceeds your current position	预览模拟（simulate=true）因赎回金额超过当前持仓而 revert。仅在 simulate=true 时返回。	redeem 设 simulate=true 且以 Redeem amount exceeds your current position. revert

40459 是兜底码，覆盖未匹配到更具体码的构建失败（如 investmentId ... is not a LP investment、amount X is less than minimum Y）。参数类错误——字段格式错、值越界、必填缺失、tick 未对齐 tickSpacing——返回 40453 而非 40459。两者均见 msg 取具体原因；上述示例仅供参考、并非穷举。

Preview revert（仅 simulate=true） —— 设 simulate=true 且模拟交易 revert 时，服务将 preview 的 errorMessage 映射为稳定错误码，而非返回 preview.success=false 的 200 软错误。映射为子串包含匹配（errorMessage 包含已配置子串即命中），由服务端配置驱动，故新增 revert 文案归类无需发版。默认将 "Redeem amount exceeds your current position." 归为 40485；errorMessage 未命中任何已配置子串时回落 40484。仅在 simulate=true 时按此方式上抛 revert；未模拟则不产生 preview，不返回这两个码。msg 始终携带原始 revert 原因。

---

服务端错误

Code	Message	原因
50000	Internal server error, please retry later	服务端发生未预期错误（如空指针、序列化错误）。若持续存在，请带上请求时间戳联系支持。
50001	Service temporarily unavailable, please retry later	上游 DeFi 数据提供方不可达或返回错误，稍后重试。

---

按接口的错误码参考

接口	可能的错误码
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, 40490, 50000, 50001
POST /api/v1/defi/data/investment/list	40001, 40301–40304, 50000, 50001
POST /api/v1/defi/data/investment/detail	40001, 40301–40304, 40490, 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 是纯计算接口，不上链，因此不会出现上链构建接口的 KYT 40434 码；且不执行预览模拟，故也不会返回 40484 / 40485。

---

排错指引

现象	可能 Code	处理
签名不一致	40102	检查 pre-hash：timestamp + METHOD + requestPath + body。requestPath 须含 /build，body 须与发送的原始 body 完全一致。
时间戳漂移	40103	用 NTP 同步系统时钟；用 X-OC-RECV-WINDOW 放宽容忍（最大 60 000 ms）。
构建被拒且原因可读	40450–40460, 40480–40485	按 code 选择恢复路径，勿按 msg。40460 模拟 revert；40482 RPC 异常→重试。40459 为兜底码——看 msg。余额不足本期不返回 40480——请设 simulate=true；由此引发的 revert 会被映射为 40484 / 40485（见下）。
simulate=true 时预览 revert	40484, 40485	模拟交易 revert。40485 = 赎回金额超过当前持仓（降低金额或减小 ratio）；40484 = 其它 revert——看 msg 取原始 revert 原因。仅在 simulate=true 时返回。新增 revert 文案归类可通过服务端 revert 文案映射配置。
claim 字段不匹配被拒	40454	按 claimType 提供必填字段（LP_FEE → investmentId + nftId；REWARD_PROTOCOL → defiProtocolId + binanceChainId；REDEMPTION → redemptionId）。
投资品未知 / 已下架	40451 / 40452	investmentId 未知或该投资品已下架、不允许此操作。用 /data/investment/list 重新获取。
LP 移除但无流动性	40457	该仓位已无剩余流动性，无可移除。
存入时健康因子被拒	40455	存入 / 借贷会使健康因子跌破协议阈值，减小金额。
地址被合规拦截	40434	地址或资金流未通过 KYT，构建被拦截。
缺地址	40001	确保 position/list 的 addresses 数组非空。
多次重试仍返回 50001	50001	上游 DeFi 数据服务降级。查看 状态页 或联系支持。