币安 API 错误 -1021Timestamp for this request：原因和修复方法

币安 API 错误 -1021 INVALID_TIMESTAMP 表示你的签名请求上的时间戳落在币安接受的窗口之外。消息通常是Timestamp for this request is outside of the recvWindow或was 1000ms ahead of the server's time。大多数情况下原因是你自己的时钟，所以解决办法是同步时钟、测量和币安服务器时间的偏移，并妥善处理剩余的网络延迟。调大 recvWindow 可以掩盖问题，但不应该是第一步。

这个错误是什么意思

币安要求签名接口（也就是涉及你账户的请求，如下单或查询余额）带上 timestamp 参数，它应该是请求创建时的毫秒时间。币安用它拒绝过期或重放的请求，这样被截获的请求不能之后再发一次。

币安的文档写明了这项检查：

if (timestamp < serverTime + 1000 && serverTime - timestamp <= recvWindow) { process } else { reject }

这是两个独立的限制，请注意每条消息对应哪个。

• 超前太多：如果你的时间戳比币安时钟超前 1,000 ms 或以上，会收到Timestamp for this request was 1000ms ahead of the server's time。你的时钟快了。
• 落后太多：如果币安处理时你的时间戳已比 recvWindow 还旧，会收到Timestamp for this request is outside of the recvWindow。你的时钟慢了，或者请求到达得太慢。

两个限制并不对称。慢的一侧默认有 5,000 ms 容忍度，快的一侧只有 1,000 ms，而调大 recvWindow 对快的一侧没有任何作用。

第一步：测量偏移

不要猜。获取服务器时间，和自己的时钟比较。这个公开接口不需要密钥。U 本位合约是 https://fapi.binance.com/fapi/v1/time，现货是 https://api.binance.com/api/v3/time。

一个简单的 Python 检查如下：

import time, requests; t0 = time.time()*1000; s = requests.get("https://fapi.binance.com/fapi/v1/time").json()["serverTime"]; t1 = time.time()*1000; print("offset ms:", s - (t0 + t1) / 2, "round trip ms:", t1 - t0)

它用往返的中点作为服务器读取时钟时刻的最佳估计。多运行几次。偏移为正表示币安时钟比你的快，也就是你的时钟慢了；偏移为负表示你的时钟快了。如果往返时间很大或波动很大，你的网络也是问题的一部分。时钟偏移指南讲了这个方法及其局限。

第二步：同步时钟

如果偏移超过几百毫秒，先修时钟。这能解决大多数情况。

• Linux：用 timedatectl 查看。如果没有服务在同步，安装并启用 chrony，然后用 chronyc makestep 立即校正大偏移。
• Windows：打开日期和时间设置，点击「立即同步」。Windows 默认同步频率很低，机器在两次同步之间可能漂移，可以考虑配置更频繁的时间服务。
• macOS：在日期与时间设置中打开「自动设置日期和时间」。
• Docker：容器使用宿主机的时钟，所以要修宿主机。在 Docker Desktop 上，笔记本休眠后内部虚拟机可能漂移，重启它常常能解决这个错误。
• 虚拟机和云服务器：暂停或迁移过的机器可能带着旧时间回来。请在里面运行时间服务。

如果系统没有默认配置，NTP Pool 的文档说明了如何设置公共时间服务器，不过大多数云服务商都提供内部时间服务，通常是更好的选择。

第三步：在正确的时刻生成时间戳

时钟正确时，如果代码过早创建时间戳，仍可能出现这个错误。检查这些原因：

• 时间戳早在发送之前就创建了。应该在签名和发送之前才创建。如果请求要经过队列或慢线程，时间戳会在等待中变旧。
• 重试循环复用了请求。重试的请求需要新的时间戳和新的签名，否则几次尝试后就会因这个错误失败。
• 单位错误。币安要求毫秒。秒级时间戳只有十位而不是十三位，会远远超出窗口。
• 客户端自己的限流。客户端限流器把已签名的请求扣留几秒，会让它超出窗口。
• 机器负载过高。CPU 饱和时，从生成时间戳到发送的延迟可能长得惊人。

第四步：必要时在客户端使用时间偏移

常见做法是启动时获取服务器时间，算出和自己时钟的差，然后加到每个时间戳上。很多客户端库提供这个选项，比如自动调整时间差。

当你无法控制系统时钟时这很有用，但它有个弱点：随着时钟继续漂移，偏移会过时。如果用这种办法，请定期刷新，并在遇到这个错误时先刷新一次再重试。修好系统时钟是更好的长期方案，因为所有软件都能受益。

第五步：谨慎对待 recvWindow

recvWindow 是 timestamp 之后请求保持有效的毫秒数，默认 5,000。币安文档把它描述为一种声明：请求必须在一定时间内处理，否则被拒绝，这是安全功能，不是麻烦。调大可能让错误消失，但要想想这意味着什么。它等于告诉币安，你愿意让几秒前创建的订单现在才执行。快速行情中，30 秒前决定的交易现在可能完全是另一笔交易。

大窗口还会掩盖真正的问题，无论是时钟漂移还是网络不稳定。如果你的时钟快了，它也完全帮不上忙，因为 1,000 ms 的限制是独立的。只能适度调大，只作为临时措施，并且只在测量清楚之后。如果发现需要很大的窗口，真正的问题在别处。

问题在网络或币安时

如果时钟正确、时间戳也在正确时刻创建，就看路径。高延迟、丢包或拥塞的代理都可能让请求耗时过长而超出窗口。第一步的往返时间能显示这一点。币安的 API 也有自己的基础设施，繁忙时可能出现短暂延迟。

偶发的孤立错误通常无害，重建请求再发即可。之前都正常的多台机器突然同时大量报错，说明问题在网络或交易所。可以对比我们对币安的读数，包括最近的时钟偏移和响应时间，并查看公告。不过我们的数据只是从我们的地点看币安的公开 API。

在代码中处理

健壮的客户端把 -1021 当作已知的、可恢复的情况，而不是一般失败。

• 重建，不要重发。用新的时间戳和签名构建新请求。
• 重试下单前先检查。这个拒绝说明这次请求没有被处理，但如果之前的尝试有其他错误，先查询订单状态，以免重复。使用唯一的客户端订单号，方便发现重复。
• 限制重试次数。紧密循环重试可能触发频率限制，频率限制指南讲了后果。
• 记录偏移和往返时间。错误再次出现时，日志能立刻告诉你是时钟漂移了还是网络变差了。
• 设置告警。-1021 比例上升是机器时钟出问题的早期信号。

其他交易所也有同样的错误吗？

有。任何使用签名请求的交易所都有类似检查，只是错误码和窗口不同。例如 Bybit 会根据自己的服务器时间检查时间戳，并有 recv_window 参数；OKX 要求在请求头中带时间戳。建议是一样的，但具体限制请读各交易所的文档。

关于 -1021 错误的常见问题

为什么在笔记本上正常、在服务器上失败，或者反过来？

因为每台机器有自己的时钟和到币安的路径。在两台机器上都运行偏移检查。云服务器的时间通常很好，而经常休眠的笔记本往往不行。

什么都没改，为什么突然开始报错？

时钟漂移很慢，偏移可能增长几周才超过限制。系统更新也可能停用时间服务，换网络可能提高延迟。

把 recvWindow 设成最大安全吗？

它能消除很多错误，但也意味着币安可能执行一个比你预期旧得多的请求，而市场可能已经变了。我们最多把它当作临时措施。

按这个顺序修复

1. 看清你收到的是两条消息中的哪一条。
2. 测量和币安服务器时间的偏移。
3. 同步系统时钟，并确认它保持同步。
4. 在签名和发送之前才创建时间戳。
5. 确保重试时重建时间戳和签名。
6. 最后才考虑适度调整 recvWindow。

相关阅读：时钟偏移与过时报价 · 交易所 API 频率限制和 429 错误 · 交易所 API 为什么返回 403 或 451

来源

币安 · 错误码 · 币安 · 基本信息和时间安全 · NTP Pool Project · 关于 Tickmark