钱包 API

错误码

响应格式

所有 Wallet API 响应（包括错误响应）均返回 HTTP 200，业务结果通过响应体中的 code 字段标识。


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

code 非零时表示请求出错，可通过 msg 字段获取可读的错误描述。

成功

错误码	说明
`0`	请求成功

参数错误

错误码	错误信息	原因	涉及接口
`40001`	`Parameter [field] error: <reason>`	请求参数校验失败——字段格式非法、值超出范围、必填参数缺失或枚举值不支持。`msg` 字段会包含具体的字段名和原因。	所有接口

40001 常见触发场景：

address 为空或缺失
pageSize 超出范围（必须满足 1 ≤ pageSize ≤ 100）
POST /token-balances-by-address 请求中 tokenContractAddresses 列表包含无效条目（binanceChainId 或 tokenContractAddress 为空）
必填的 @RequestParam 或 @RequestBody 字段缺失

认证与授权错误

以下错误码由 API 网关在请求到达 Wallet 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` 范围（默认 ±5000ms）
`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 行为，如频繁切换地区或同时多地区访问

服务端错误

错误码	错误信息	原因
`50000`	`Internal server error, please retry later`	服务端发生未预期的错误（如空指针、序列化异常）。若问题持续存在，请携带请求时间戳联系技术支持。
`50001`	`Service temporarily unavailable, please retry later`	上游余额数据提供方不可达或返回错误。请稍后重试。

各接口错误码速查

接口	可能的错误码
`GET /api/v1/dex/balance/supported/chain`	`40001`, `50000`
`GET /api/v1/dex/balance/all-token-balances-by-address`	`40001`, `50000`, `50001`
`POST /api/v1/dex/balance/token-balances-by-address`	`40001`, `50000`, `50001`
`GET /api/v1/dex/post-transaction/transactions-by-address`	`40001`, `50000`, `50001`
`GET /api/v1/dex/post-transaction/transaction-detail-by-txhash`	`40001`, `50000`, `50001`

排查指引

现象	可能的错误码	处理方式
签名不匹配	`40102`	检查签名原文格式：`timestamp + METHOD + requestPath + body`，确保 `requestPath` 包含完整的原始查询字符串
时间戳偏差	`40103`	使用 NTP 服务器同步系统时钟；可通过 `X-OC-RECV-WINDOW` 扩大容忍范围（最大 60000ms）
pageSize 超出范围	`40001`	将 `pageSize` 控制在 `[1, 100]` 范围内
持续返回 `50001`	`50001`	上游余额服务降级，请查看状态页或联系技术支持

Last modified on July 2, 2026

钱包 API 介绍概览

钱包 API

错误码

响应格式

所有 Wallet API 响应（包括错误响应）均返回 HTTP 200，业务结果通过响应体中的 code 字段标识。


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

code 非零时表示请求出错，可通过 msg 字段获取可读的错误描述。

成功

错误码	说明
`0`	请求成功

参数错误

错误码	错误信息	原因	涉及接口
`40001`	`Parameter [field] error: <reason>`	请求参数校验失败——字段格式非法、值超出范围、必填参数缺失或枚举值不支持。`msg` 字段会包含具体的字段名和原因。	所有接口

40001 常见触发场景：

address 为空或缺失
pageSize 超出范围（必须满足 1 ≤ pageSize ≤ 100）
POST /token-balances-by-address 请求中 tokenContractAddresses 列表包含无效条目（binanceChainId 或 tokenContractAddress 为空）
必填的 @RequestParam 或 @RequestBody 字段缺失

认证与授权错误

以下错误码由 API 网关在请求到达 Wallet 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` 范围（默认 ±5000ms）
`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 行为，如频繁切换地区或同时多地区访问

服务端错误

错误码	错误信息	原因
`50000`	`Internal server error, please retry later`	服务端发生未预期的错误（如空指针、序列化异常）。若问题持续存在，请携带请求时间戳联系技术支持。
`50001`	`Service temporarily unavailable, please retry later`	上游余额数据提供方不可达或返回错误。请稍后重试。

各接口错误码速查

接口	可能的错误码
`GET /api/v1/dex/balance/supported/chain`	`40001`, `50000`
`GET /api/v1/dex/balance/all-token-balances-by-address`	`40001`, `50000`, `50001`
`POST /api/v1/dex/balance/token-balances-by-address`	`40001`, `50000`, `50001`
`GET /api/v1/dex/post-transaction/transactions-by-address`	`40001`, `50000`, `50001`
`GET /api/v1/dex/post-transaction/transaction-detail-by-txhash`	`40001`, `50000`, `50001`

排查指引

现象	可能的错误码	处理方式
签名不匹配	`40102`	检查签名原文格式：`timestamp + METHOD + requestPath + body`，确保 `requestPath` 包含完整的原始查询字符串
时间戳偏差	`40103`	使用 NTP 服务器同步系统时钟；可通过 `X-OC-RECV-WINDOW` 扩大容忍范围（最大 60000ms）
pageSize 超出范围	`40001`	将 `pageSize` 控制在 `[1, 100]` 范围内
持续返回 `50001`	`50001`	上游余额服务降级，请查看状态页或联系技术支持

Last modified on July 2, 2026

钱包 API 介绍概览