响应格式
链上交易 API 的所有响应（包括错误响应）均返回 HTTP 200。业务结果通过响应体中的 code 字段标识。
{
"code": 0,
"msg": "success",
"data": { ... },
"timestamp": 1718000000000
}
code 非零时表示发生了错误，可通过 msg 字段获取可读的错误描述。
成功
参数错误
| 错误码 | 错误信息 | 原因 | 涉及接口 |
|---|
40001 | Parameter [field] error: <reason> | 请求参数校验失败 — 字段格式不合法、值超出范围、必填参数缺失或枚举值不支持。msg 字段中会包含具体的字段名称和失败原因。 | 所有接口 |
40001 常见触发场景：
binanceChainId 为空或不在支持链列表中address 为空或格式不合法- 广播请求中
evmTx 和 solTx 均未提供（二者必须提供其一）
evmTx.gasLimit 或 evmTx.gasPrice 不是合法的数字字符串limit 超出范围 [1, 100]- 必填的
@RequestParam 或 @RequestBody 字段缺失
认证与授权错误
以下错误码由 API 网关在请求到达链上交易 API 服务之前进行拦截。
| 错误码 | 错误信息 | 原因 |
|---|
40101 | Invalid API Key | X-OC-APIKEY 请求头缺失、格式不合法，或该 API 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 没有访问此接口所需的权限 |
频率限制错误
| 错误码 | 错误信息 | 原因 |
|---|
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（了解您的交易）
KYT 合规检查在广播交易前执行，以下四个错误码均可能由 POST /broadcast-transaction 返回。
| 错误码 | 错误信息 | 原因 |
|---|
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，客户端需向用户展示风险确认提示，并在用户明确确认后重新提交 |
40434 | KYT verification failed. Transaction involves high-risk address | 广播前的最终 KYT 检查未通过，交易被拦截 |
链上交易 API 业务错误
链支持
| 错误码 | 错误信息 | 原因 | 涉及接口 |
|---|
40411 | This chain is not supported | 提供的 binanceChainId 不在支持链白名单中，或该链已通过配置临时禁用 | /gas-price、/gas-limit、/simulate、/broadcast-transaction |
广播
| 错误码 | 错误信息 | 原因 | 涉及接口 |
|---|
40431 | Transaction broadcast failed, please check gas settings and retry | wallet-direct RPC 服务拒绝了该交易或未返回结果。常见子原因：gas 不足、nonce 冲突、RPC 节点错误或原始交易字节格式不合法 | /broadcast-transaction |
服务端错误
| 错误码 | 错误信息 | 原因 |
|---|
50000 | Internal server error, please retry later | 服务端发生意外错误（如空指针、序列化错误、下游服务故障）。如问题持续出现，请携带请求时间戳联系技术支持 |
50001 | Service temporarily unavailable, please retry later | 上游依赖服务（如交易历史服务、订单服务）不可达或返回错误。请稍后重试 |
各接口错误码速查
| 接口 | 可能返回的错误码 |
|---|
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 |
排查指引
| 现象 | 可能的错误码 | 处理建议 |
|---|
| 签名不匹配 | 40102 | 检查预签名字符串格式：timestamp + METHOD + requestPath + body，确保 requestPath 包含完整的原始查询字符串 |
| 时间戳偏差过大 | 40103 | 使用 NTP 服务器同步系统时钟；可通过 X-OC-RECV-WINDOW 扩大容忍范围（最大 60 000 ms） |
| 广播被拒绝 | 40431 | 确认 gasLimit 和 gasPrice 设置充足；广播前先调用 /gas-price 和 /gas-limit 获取当前估算值 |
| KYT 高风险拦截 | 40311/40312/40313 | 目标地址已被标记为风险地址；制裁地址的交易无法继续处理 |
| KYT 中风险提示 | 40314 | 向用户展示风险警告，并在用户明确确认后携带确认标志重新提交 |
| 链不支持 | 40411 | 调用 GET /api/v1/dex/pre-transaction/supported/chain 获取当前支持链白名单 |
多次重试均返回 50001 | 50001 | 历史记录或订单服务出现故障，请查看状态页面或联系技术支持 |
Last modified on
