错误代码

ZTDX 暴露两套 API 接口面，各自使用独立的错误体系。返回哪一套取决于 你调用的路径，而不是使用的凭证。

1. 原生接口面 —— /api/v1/*

错误由 HTTP 状态码加一个字符串错误码组成。响应体存在两种形态：

Handler 层错误（参数校验、业务逻辑）使用扁平结构：

{ "error": "杠杆倍数必须在1-50之间", "code": "INVALID_LEVERAGE" }

部分 handler 会附加可选的 details 对象（例如登录端点的时间戳诊断信息）。

中间件 / 框架层错误（鉴权、通用失败）使用 ApiResponse 信封：

{
  "success": false,
  "data": null,
  "error": { "code": "SIGNATURE_INVALID", "message": "Timestamp outside recv window" },
  "timestamp": 1778716800
}

常见字符串错误码

HTTP	错误码	含义
401	UNAUTHORIZED	Authorization 头缺失或格式错误
401	INVALID_TOKEN	JWT 无效或已过期
401	INVALID_API_KEY	未知的 X-MBX-APIKEY
401	API_KEY_DISABLED	API key 存在但已被停用
401	SIGNATURE_INVALID	HMAC 签名不匹配，或 timestamp 超出 ±60s 窗口；EIP-712 登录签名无效时也返回此码
403	IP_NOT_ALLOWED	调用方 IP 不在该 API key 的白名单内
400	MISSING_SIGNATURE / MISSING_TIMESTAMP	JWT 鉴权的交易请求缺少请求体内的 EIP-712 signature / timestamp
400	TIMESTAMP_EXPIRED	EIP-712 请求体 timestamp 超出有效窗口（下单：±300 秒；登录：±300 秒）
400	INVALID_SIGNATURE_FORMAT	EIP-712 签名无法解析
400	INVALID_LEVERAGE	杠杆超出 1..max_leverage（symbol 无市场配置时默认上限 50）
400	INVALID_AMOUNT / INVALID_PRICE	数量 / 价格为非正数
400	PRICE_REQUIRED	限价类订单未提供价格
400	TRIGGER_PRICE_REQUIRED	TP/SL 订单缺少 trigger_price
400	NOTIONAL_TOO_SMALL	订单名义价值低于 min_order_size_usd（默认 $10）
400	INSUFFICIENT_BALANCE	可用余额低于所需保证金
404	ORDER_NOT_FOUND / POSITION_NOT_FOUND	引用的实体不存在
500	INTERNAL_ERROR / DB_ERROR / DATABASE_ERROR	服务端故障
502	SHARD_PROXY_ERROR	symbol 分片转发失败

此表覆盖最常遇到的错误码；各端点页会记录端点特有的错误码 （如 账户 PnL）。

2. 开发者接口面 —— /fapi/*

Binance 风格错误：JSON 响应体带负整数 code 与 msg 字符串。

{ "code": -4028, "msg": "Leverage 200 is not valid. Max: 125" }

/fapi 错误码全表维护在 错误代码（U 本位合约）。

说明

• 两套体系互不混用：/api/v1 不会返回 Binance 数字错误码，/fapi 也不会返回上面的字符串错误码响应体。
• 当 symbol 没有市场配置时，两套接口面校验用的杠杆上限不同： /api/v1 回退到 50，/fapi/v1/leverage 回退到 125。