响应格式
所有行情 API 响应（包括错误）均返回 HTTP 200。业务结果通过响应体中的 code 字段表示。
{
"code": 0,
"msg": "success",
"data": { ... },
"timestamp": 1718000000000
}
code 非零时表示发生错误，可通过 msg 字段获取可读的错误描述。
成功
参数错误
| 错误码 | 消息 | 原因 | 涉及接口 |
|---|
40001 | Parameter [field] error: <reason> | 请求参数校验失败 — 字段格式无效、值超出范围、缺少必填参数或枚举值不支持。msg 字段会包含具体字段名和原因说明。 | 所有接口 |
40001 常见触发场景：
binanceChainId 为空或不在支持的链列表中tokenContractAddress 为空或格式无效- 批量请求列表超过 100 条（
POST /price、POST /price-info）
limit 超出范围（如 GET /trades 要求 1 ≤ limit ≤ 500）walletAddressFilter 包含超过 2 个逗号分隔的地址tagFilter 设置了不支持的值bar（K 线周期）不是允许的枚举值之一rankBy、rankingTimeFrame、pageId 或 size 超出热门代币查询的允许范围- 请求中缺少必填的
@RequestParam 参数
鉴权与授权错误
以下错误码由 API 网关在请求到达行情 API 服务之前进行拦截。
| 错误码 | 消息 | 原因 |
|---|
40101 | Invalid API Key | X-OC-APIKEY 请求头缺失、格式错误，或该密钥已被删除/禁用 |
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 活动，如频繁切换地理位置或同时多地区访问 |
行情 API 业务错误
链支持
| 错误码 | 消息 | 原因 | 涉及接口 |
|---|
40411 | This chain is not supported | 提供的 binanceChainId 不在支持的链白名单中，或该链已通过配置临时禁用 | 所有含 binanceChainId 参数的接口 |
服务端错误
| 错误码 | 消息 | 原因 |
|---|
50000 | Internal server error, please retry later | 发生了意外的服务端错误（如空指针、序列化错误）。如问题持续，请携带请求时间戳联系技术支持 |
50001 | Service temporarily unavailable, please retry later | 上游数据提供商（如 CoinMarketCap DEX 服务）不可达或返回错误，请稍后重试 |
各接口错误码速查
| 接口 | 可能的错误码 |
|---|
GET /api/v1/dex/market/supported/chain | 40001、50000 |
POST /api/v1/dex/market/price | 40001、40411、50000、50001 |
POST /api/v1/dex/market/price-info | 40001、40411、50000、50001 |
GET /api/v1/dex/market/candles | 40001、40411、50000、50001 |
GET /api/v1/dex/market/token/search | 40001、50000、50001 |
POST /api/v1/dex/market/token/basic-info | 40001、40411、50000、50001 |
GET /api/v1/dex/market/token/hot-token | 40001、50000、50001 |
GET /api/v1/dex/market/token/advanced-info | 40001、40411、50000、50001 |
GET /api/v1/dex/market/token/top-liquidity | 40001、40411、50000、50001 |
GET /api/v1/dex/market/token/holder | 40001、40411、50000、50001 |
GET /api/v1/dex/market/token/top-trader | 40001、40411、50000、50001 |
GET /api/v1/dex/market/trades | 40001、40411、50000、50001 |
排查指南
| 现象 | 可能的错误码 | 处理建议 |
|---|
| 签名不匹配 | 40102 | 检查预哈希字符串的拼接方式：timestamp + METHOD + requestPath + body，确保 requestPath 包含完整的原始查询字符串 |
| 时间戳偏差 | 40103 | 使用 NTP 服务器同步系统时钟，或通过 X-OC-RECV-WINDOW 扩大容忍范围（最大 60 000 ms） |
| 链不支持 | 40411 | 在构建请求前先调用 GET /api/v1/dex/market/supported/chain 获取当前白名单 |
| 批量请求超限 | 40001 | 将代币列表拆分为每次不超过 100 条的批次请求 |
多次重试均返回 50001 | 50001 | 上游数据服务降级，请查看状态页或联系技术支持 |
Last modified on
