同一段代码昨天能下单,今天全是 -1021:recvWindow、时间戳偏移与五个漂移来源

同一段代码,昨天还能下单,今天所有请求都返回 -1021;或者本地跑得好好的,一上服务器就全是签名错误。这类问题几乎都不在密钥上,而在两个数字:请求里的 timestamp 和它旁边的 recvWindow。

交易所的私有接口要求每个请求带签名,签名里包含毫秒时间戳。服务端收到后先做一件事:比较自己的时间和请求里的时间,差值超过窗口就直接拒绝。这条规则的目的不是刁难,而是让被截获的请求在几十秒后自动失效。理解它,比反复重试有用得多。

一、校验发生在解密之前

以常见的 HMAC-SHA256 签名为例,签名串通常由这几段拼起来:timestamp + method + requestPath + body,用 API secret 做 HMAC,再 Base64 或 hex 编码。服务端收到后用自己的 secret 重算一遍,同时检查时间差。顺序是:先看时间差是否在窗口内,再验签名是否一致,最后才看权限和余额。

这意味着一个反直觉的现象:时钟偏移过大时,你连「签名错了」都看不到,直接收到 -1021。很多人以为是 secret 填错了,于是重新生成密钥,把问题拖得更久。

环节服务端检查什么失败时的典型报错
时间|服务端时间 − 请求时间| ≤ recvWindow(常见默认 5,000 毫秒,可上调到 60,000)-1021 Timestamp for this request is outside of the recvWindow
签名用同一串参数重算 HMAC 是否一致-1022 Signature for this request is not valid
密钥状态Key 是否存在、是否过期、IP 是否在白名单-2015 Invalid API-key, IP, or permissions
权限该 Key 是否开了对应业务(现货/合约/提币)-2015 或 -1002

四个环节的顺序很重要:前一个不过,后面的错误根本不会出现。所以排查要从上往下,而不是从「我怀疑密钥坏了」开始。想先把密钥本身的权限边界理清楚,可以对照API key 四类权限的最小化清单。

二、五个让时间戳漂掉的原因

  • 本机时钟本来就不准。普通桌面系统一天漂几十毫秒到几秒都正常,长期不联网同步就可能超过 5 秒窗口。
  • 时区被误当成时间。时间戳必须是 Unix 毫秒(UTC 起点算起),不是本地时间字符串,也不是秒级。2026-11-03 15:00:00 这种格式直接送进去必然失败。
  • 秒和毫秒混用。10 位是秒,13 位是毫秒。差 1,000 倍,窗口再宽也过不去。
  • 系统休眠或虚拟机挂起。恢复后时钟可能跳变,长连接里的进程还拿着旧时间。
  • 代理/网关改了请求。中间层重排参数、加空格、改用例,签名串和实际发送的不再一致——这类会表现为 -1022,而不是 -1021。

对应地,只有第一条和第四条能靠 recvWindow 硬扛,其余几条调窗口没用。把窗口从 5,000 调到 60,000 治不了格式错误,只会把重放窗口一起放大:一个 60 秒内被截获的请求,仍然可以被重放。顺带一提,同一批请求的权重与退避策略是另一套规则,见限频权重与退避清单。

三、正确做法:先问服务器现在几点

几乎所有主流交易所都提供公开的时间接口(形如 /api/v3/time),返回服务端的毫秒时间。稳定的做法是:

  1. 启动时取一次服务端时间,算出 offset = serverTime − localTime;
  2. 之后每次签名用 localNow + offset,而不是直接使用本机时间;
  3. 每 5–10 分钟刷新一次 offset,网络抖动会让它缓慢变化;
  4. recvWindow 保持在 5,000 毫秒这个量级,只在确实有高延迟链路时才上调;
  5. 下单请求带 newClientOrderId,超时重试时用它做幂等,避免「第一次其实成功了,第二次又下一单」。

第 5 条经常被忽略:超时重试是时间戳问题最常见的连带损失。请求发出去、响应没回来,程序重试一次,结果变成两笔仓位。给每个逻辑订单一个固定 ID,是唯一可靠的去重手段。而重试带来的几十到几百毫秒延迟本身也会换成滑点,量化关系见下单延迟折算成滑点的公式。

四、把窗口当作安全参数,而不是兼容参数

recvWindow 的本质是「这张签名票据的有效期」。窗口越大,被截获的请求可被利用的时间越长;窗口越小,对时钟和延迟越敏感。生产环境里合理的组合是:本地维护 offset、窗口保持默认、对超时做幂等重试。把窗口调到 60,000 只是在掩盖一个本该修的时钟问题。

另外两个容易踩的坑:一是并发请求共用同一个时间戳变量,跨秒边界时签名和发送的时间不一致;二是把 timestamp 放在 body 之外,却按 body 内容计算签名,两边对不上。前者靠每次请求重新取时间解决,后者靠对齐文档里的签名串顺序解决。

常见问题

所有接口都 -1021,是不是 IP 被风控了?

不是。IP 问题通常返回 -2015 或 403。-1021 只说明时间差不合格,先核对时间戳位数和本机时钟。

把 recvWindow 调到最大能彻底解决吗?

不能。它只能容忍漂移,不能修正格式错误;而且会放大重放风险。先修时钟,再谈窗口。

只有下单接口报错,查询接口正常,为什么?

下单对时间更敏感,且往往带更严格的幂等与风控校验;有些实现里查询接口不校验时间戳。不要用「查询能通」推断签名和时间没问题。

本文只解释接口鉴权机制与排查顺序,不构成任何投资建议。文中窗口数值为常见默认区间(5,000 毫秒,上限 60,000 毫秒),具体以所用平台文档为准。

安装 App