响应格式
所有兑换 API 响应（包括错误）均返回 HTTP 200。业务结果由响应体中的 code 字段标识。
{
"code": 0,
"msg": "success",
"data": { ... },
"timestamp": 1718000000000
}
非零 code 表示错误，详情参见 msg 字段的描述。
成功
参数错误
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40001 | Parameter [field] error: <reason> | 请求参数校验失败 — 字段格式无效、值超出范围、必填参数缺失或枚举值不支持。msg 字段包含具体字段名称和原因。 | 所有接口 |
常见 40001 触发场景：
chainId 不是正整数或不在支持链白名单中fromTokenAddress / toTokenAddress 不是有效的 EVM 地址或 Solana 公钥amount 不是正数字符串slippagePercent 不是有效的小数字符串gasLevel 不是允许的枚举值之一- 必填的
@RequestParam 缺失
- 询价 Ondo（RFQ）代币对时缺少
userWalletAddress
鉴权错误
以下错误码由 API 网关在请求到达兑换 API 服务前强制执行。
| 码值 | 消息 | 原因 |
|---|
40101 | Invalid API Key | X-OC-APIKEY 头缺失、格式错误，或对应 Key 已被删除/禁用 |
40102 | Signature error | X-OC-SIGN 的值与预期的 HMAC-SHA256 或 Ed25519 签名不匹配。对于 /order/submit：userSignature 与 /quote 中的 userWalletAddress 不匹配 — 确认签名钱包正确且使用了 EIP-712 typed data 签名（非普通文本签名） |
40103 | Timestamp expired | X-OC-TIMESTAMP 超出相对服务器时间允许的 recv_window 范围（默认 ±5000 毫秒） |
40104 | Permission denied | API Key 没有访问该接口所需的权限 |
频率限制错误
| 码值 | 消息 | 原因 |
|---|
42900 | Request rate limit exceeded. Please refer to the API docs and reduce request frequency | IP、API Key、用户或接口级别的频率限制已达上限。根据响应头 Retry-After 指示的时间后重试 |
合规错误
IP 合规
| 码值 | 消息 | 原因 |
|---|
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 活动，如频繁切换位置或多地区并发访问 |
KYT（了解你的交易）
| 码值 | 消息 | 原因 |
|---|
40311 | Transaction rejected due to high-risk address | 交易对手地址风险评分 ≥ 70，交易被直接拒绝 |
40312 | Address is on sanctions list | 地址匹配 OFAC 或联合国制裁名单 |
40313 | Transaction rejected due to risky fund origin | 上游资金溯源（3-5 跳）发现与制裁地址、赌博网站或暗网实体关联 |
40314 | Medium-risk address detected. Please confirm to proceed | 风险评分 40-69，客户端须向用户展示确认提示并在用户明确确认后重新提交 |
兑换 API 业务错误
链支持
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40411 | This chain is not supported | 传入的 chainId 不在支持链白名单中，或该链已通过配置临时禁用 | /approve-transaction、/quote、/swap、/history |
40412 | DEX contract not configured for this chain, please contact administrator | 该链的链上 approve 合约地址尚未在后端配置，属于运维配置问题，请联系支持 | /approve-transaction |
报价
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40401 | Quote expired. Please request a new quote | quoteId 在缓存中未找到 — /quote 调用后 30 秒 TTL 已过期，或 ID 无效 | /swap |
40421 | Insufficient liquidity for this trading pair | 当前没有活跃的流动性提供商（vendor）可为请求的链或代币对报价 | /quote |
40441 | No valid quote result from any vendor, please retry later | 所有 vendor 均已联系但均未返回有效报价（响应为空、包含错误或输出数量为 0） | /quote |
40442 | fromTokenAddress and toTokenAddress must be different | fromTokenAddress 和 toTokenAddress 相同 | /quote |
兑换
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40461 | No valid swap route found, please try other token pair | quoteId 对应的路由引用了未知或缺失的 vendor — 请重新询价后重试 | /swap |
40462 | quoteId does not match request parameters | quoteId 在缓存中存在，但一个或多个参数与原始询价请求不一致（chainId、fromTokenAddress、toTokenAddress 或 amount） | /swap |
40463 | Price impact exceeds protection threshold | vendor 报告的价格影响超过保护阈值（默认 90%）。传入 priceImpactProtectionPercent=100 可禁用此检查 | /swap |
40464 | slippagePercent out of allowed range | slippagePercent 不是有效数字，或超出允许范围：EVM 链 [0, 100]，Solana [0, 99.9] | /swap |
40465 | Vendor swap call failed, please retry later | vendor 构造 swap 交易失败。常见子原因：vendor 超时、响应为 null、Gas 估算失败、Solana ALT 账户解析错误、EVM 代理地址未配置、或缺少 API Key 上下文。稍后重试 | /swap |
Gas
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40432 | Failed to estimate gas price, please retry later | Gas 价格服务（wallet-direct）未返回数据，通常是瞬时问题，稍后重试 | /approve-transaction |
RFQ 订单（权益代币错误）
以下错误码专用于权益 / RWA 代币交易（Ondo 和 BStock 代币）。
| 码值 | 消息 | 原因 | 影响接口 |
|---|
40374 | RWA_INSUFFICIENT_LIQUIDITY | RWA 代币在所有 vendor（LiquidMesh + PcsXRfq）均无可用流动性。常见于新上市或流动性较差的权益代币。 | /quote |
40365 | ONDO_TOKEN_PAIR_NOT_SUPPORTED | 代币对两侧均不是 Ondo 代币，但已启用仅 Ondo 模式（only-ondo-mode=true）。确保 fromTokenAddress 或 toTokenAddress 中至少有一个是 Ondo 代币。 | /quote |
40366 | ONDO_MAX_SINGLE_ORDER_LIMIT | 订单数量超过做市商为该 Ondo 代币配置的单笔最大限额。 | /quote |
40367 | ONDO_MARKET_STATE_NOT_TRADABLE | Ondo 代币的底层资产市场当前处于关闭状态（如美股交易时段外或停牌期间）。待市场重新开放后重试。 | /quote |
40368 | ONDO_STABLECOIN_PAIR_INVALID | Ondo 代币配对了不在白名单中的稳定币（如 BSC 上须与 USDT 配对，ETH 上须与 USDC 配对）。请使用支持的稳定币作为对价代币。 | /quote |
40369 | BSTOCK_INVALID_TRADING_TIME | BStock 代币的底层证券交易所当前处于非交易时段。请在交易时段内重试。 | /quote |
40370 | BSTOCK_INVALID_TRADING_PAIR | BStock 代币配对了不在 BStock 白名单中的代币。请使用支持的对价代币。 | /quote |
40375 | ONDO_FROM_USD_AMOUNT_TOO_SMALL | Ondo 询价的 fromTokenAmount 低于最小 USD 门槛。请提高订单金额以满足最低要求（具体最低金额在 msg 中返回，如 "Minimum order amount is 20 USD."）。 | /quote |
42901 | ORDER_SUBMIT_IN_PROGRESS | 相同 requestId 的并发提交请求已在处理中。等待首次请求完成后，使用相同 requestId 重试。 | /order/submit |
服务端错误
| 码值 | 消息 | 原因 |
|---|
50000 | Internal server error, please retry later | 服务端发生意外错误（如空指针、数据库故障、序列化错误）。如问题持续，请携带请求时间戳联系支持 |
50001 | Service temporarily unavailable, please retry later | 上游依赖（如交易历史服务）不可达或返回错误。稍后重试 |
各接口错误码映射
| 接口 | 可能的错误码 |
|---|
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、50000 |
GET /swap | 40001、40401、40411、40461、40462、40463、40464、40465、50000 |
GET /history | 40001、40411、50001、50000 |
POST /order/submit | 40001、40101、40102、40401、42901、50000 |
GET /order/{orderId} | 40001、40101、50000 |
排查指南
| 现象 | 可能的错误码 | 处理建议 |
|---|
| API 签名不匹配 | 40102 | 验证预哈希字符串构造：timestamp + METHOD + requestPath + body。确保 requestPath 包含原始查询字符串 |
| RFQ 用户签名被拒绝 | 40102 | 确保 userSignature 是对 rfq.typedDataToSign 的 EIP-712 签名（使用 eth_signTypedData_v4），且签名钱包与 userWalletAddress 一致 |
| 时间戳偏差 | 40103 | 将系统时钟与 NTP 服务器同步。使用 X-OC-RECV-WINDOW 扩展容差（最大 60000 毫秒） |
| 询价成功但兑换失败 | 40401 | 立即在 /quote 后调用 /swap，quoteId TTL 为 30 秒 |
| 兑换返回参数不匹配 | 40462 | 确保传给 /swap 的 chainId、fromTokenAddress、toTokenAddress 和 amount 与 /quote 请求完全一致 |
| 价格影响警告 | 40463 | 减少交易金额，或传入 priceImpactProtectionPercent=100 跳过检查（大额订单不建议） |
| 链不支持 | 40411 | 调用 GET /supported/chain 获取当前白名单后再构建请求 |
持续返回 50001 | 50001 | 历史记录服务降级，请检查状态页面或联系支持 |
| Ondo 代币询价失败 | 40367 | 底层资产市场已关闭，请确认美股交易时段并在市场重新开放后重试 |
| BStock 代币不可用 | 40369 | 非交易时段，请在证券交易所交易时间内重试 |
| RWA 代币无报价 | 40374 | 该代币当前无任何 vendor 流动性，可尝试其他代币或稍后重试 |
/order/submit 并发重复被拒绝 | 42901 | 等待进行中的请求处理完毕，然后使用相同 requestId 重试 |
Last modified on
