独立指南 · 币安与第三方工具
LINKDESKCONNECTION FIELD NOTESTOOLS · ACCESS · CONTROL
连接更清楚,授权更有数。
LINKDESK / 04 / TROUBLESHOOT

-1021 与 -1022:把时钟问题和签名问题分开查

从运行位置、生成时间和实际发送参数入手,建立不会暴露秘密的鉴权故障记录。

LINKDESK 编辑整理 · · 11 分钟阅读
先看结论

-1021 先查请求时间是否被接受;-1022 先查签名是否与凭证和实际参数匹配。更换权限无法替代这两条诊断路径。

时钟、参数编码、签名分别检查。图中序号用于分组,不表示遇到 -1022 就一定要先改电脑时间。

先取得原始类别,别被连接失败四个字带偏

工具弹出的“连接失败”可能把多个错误合并显示。先取得不包含秘密的错误码、发生时间、工具版本和当时执行的功能。若是托管服务,应让提供方给出脱敏的上游错误,而不是让你反复修改账户设置。日志时间最好同时保留时区,避免把本地时间与服务器时间直接相减,得到一个看似很大的偏差。

-1021:需要检查的是执行进程的时间

笔记本右下角时钟正确,不代表云端任务所在机器的系统时间正确。先确定到底由哪台机器生成请求时间戳,再由维护者核对该机器的时间同步状态。另一个容易漏掉的环节是排队:程序可能先生成带时间的请求,再等很久才真正发送。此时只修正系统时钟仍不够,需要确认时间戳是在请求接近发送时生成,而不是任务入队时就固定。

接收窗口不是万能延迟开关

官方 REST 说明中的 recvWindow 单位是毫秒,默认值为 5000,最大值为 60000。它涉及请求有效时间,不是把任何错误变成成功的补丁。维护者应先核对单位和实际网络延迟,再判断是否需要合理调整。若发送方时钟明显超前,盲目扩大窗口也不能解决所有时间判定问题。不要在不理解程序实现时把网上一个大数抄进全部配置。

-1022:比较的是实际签名输入

把“签名时的参数内容”和“网络实际发出的参数内容”作为两份对象核对。中间若经过表单编码、额外空白、换行、字符转义或参数拼接,最终字节可能已经不同。对用户而言,无需把真实请求放进在线签名计算器;应要求维护者在受控环境使用虚构参数建立最小复现,再与当前官方签名例子核对。真实秘密不应该成为公开故障报告的一部分。

密钥配对与算法要单独确认

换过钥匙后报签名错误,先检查 API 标识是否仍与对应秘密或私钥成对。文件名相似、旧环境变量仍生效、服务未重启,都值得维护者按配置来源逐项排查,但不能未检查就断言是哪一种。RSA、Ed25519 与 HMAC 的实现不能通过改一个名称互换。若工具没有支持当前类型,用户扩大账户读取或交易权限也不能给它补上签名能力。

只改一个变量,记录一次结果

设想同一只读同步先报时间错误,校时后改报签名错误。新的错误是诊断线索,不意味着前一步一定无效。每次记录改了什么、何时重新发起、返回哪个类别;避免同时换网络、换钥匙、改权限,把证据冲散。如果一次修改后工具仍展示旧提示,确认它是否真的发起了新任务,而不是把缓存中的最后错误重新显示出来。

交给维护者的材料要能复现而不泄密

建议提供功能名、环境、版本、UTC 时间段、错误码,以及最近发生的升级或配置变更。可记录采用哪种算法和时间单位,但不要记录完整 API 标识、Secret、私钥、签名或包含账户信息的响应。若维护者确实需要更细日志,先要求明确哪些字段必需、怎样脱敏、通过什么私密渠道传递,以及完成排查后如何处理这些材料。

如何判定本次排查结束

对已修复的只读路径发起新请求,确认返回新数据、时间标记合理,并观察原故障触发条件是否仍会出现。例如问题发生于机器休眠恢复后,就要在受控条件下检查同类恢复流程。不要以一次正常结果覆盖所有场景,也不要为了证明稳定性持续高频发送请求。把最终原因写成可验证的配置或程序问题,而不是笼统的“币安不稳定”。

把一次请求拆成六个时刻

维护者可以画出任务创建、参数生成、签名完成、进入发送队列、真正发出和收到响应六个时刻。它们通常发生得很近,但不应因此被视为同一个瞬间。如果任务先做好全部签名再排队,时间窗口在等待期间也会流逝。相反,界面上的任务创建时间并不能直接证明请求时间戳错误,因为程序可能在发送前重新生成。需要从实现或脱敏时间记录看实际路径,不能只凭一个日志标签猜测。

这张图还可以帮助区分用户看到的延迟与请求本身的延迟。页面等待很久,可能是任务根本没轮到执行;请求迅速收到错误,也可能是生成的时间早已过期。不同原因对应不同处理,不能统称网络慢。

时区显示与时间戳单位不要混在一起

用户看到的 UTC、北京时间或乌兰巴托当地时间,是人阅读日期时采用的表达方式;API 参数采用的时间值及单位由接口说明约束。把电脑界面改成另一个时区,不应被当成修复时间戳计算的通用方法。维护者需要检查程序使用的时间来源、转换过程和最终发送单位。一个看上去有更多位数的数字,也不能只凭长度判断正确。

故障记录可以保留统一 UTC 时间,并注明原日志采用的时区。若存在多个系统,把各自的事件时间与来源写清楚,先对齐可比较的对象,再谈偏差。不要从截图中读一个时间,与另一个请求的记录相减后得出确定结论。

睡眠恢复、容器重建与云任务重启

如果问题只在电脑休眠后出现,维护者应检查恢复过程里的时钟与连接初始化,而不是每次手动重建账户凭证。若问题发生在重新部署后,先确认运行的进程读取哪份配置、系统时间服务是否正常,以及日志记录是否来自新实例。容器和宿主机的关系需要按实际平台检查,本页不为所有运行环境指定同一种修复命令。

用户可以做的有效记录是“正常运行多久、经历了什么事件、事件后第一次请求何时失败”。这样的触发条件比“偶尔报错”更具体,也减少支持方要求大量无关账户数据的可能。

参数编码问题怎样做不含秘密的复现

开发者可以选择不对应真实账户或资产的虚构参数,固定输入,并观察每次编码后字符串是否一致。重点不是拿虚构请求去真实账户上试,而是在本地重现拼接与编码过程。记录字段名称、字符类别和长度,通常比打印完整生产请求更适合共享讨论。若某次升级改变了库的参数处理方式,应对照升级前后的行为,而不是把历史教程里的结果当成当前版本必然输出。

当非 ASCII 字符、空格或特殊符号参与参数时,更应查当前接口签名说明。不要在没有核对之前自行发明“所有参数一律这样编码”的规则,再把它套到不同 API 产品。

配置来源可能不止一个文件

同一程序可能从启动参数、环境变量、本地文件或托管秘密服务读取配置。编辑你看得见的文件后,实际运行值仍可能来自优先级更高的另一处。这是维护者需要依据程序说明确认的关系,不是让用户把所有文件内容发来。可以只记录来源类型、配置标签和加载时刻,再在受控环境检查配对关系。

服务重启也不是万能步骤:如果重启后仍读旧来源,问题会继续存在。先解释配置如何进入进程,再决定是否需要重新加载,能避免反复保存、刷新、重建钥匙却始终没有改变实际请求。

错误从一个类别变成另一个类别时

鉴权流程可能有多个检查点。修复一个阻碍后,后续检查才暴露出来,因此错误码变化值得保留。你不需要据此推断平台内部的完整检查顺序,只要把每次尝试的输入变更和响应类别对应起来。若系统同时有多个后台节点,还应确认两次请求来自同一个受控版本,而不是把两个节点的不同配置误认为同一请求的演进。

对用户而言,最有帮助的是要求维护者说明当前证据支持哪一步已经通过、哪一步仍待查。没有证据的部分可以标为未知,不必为了让工单看上去有进展而给出确定答案。

怎样约束诊断日志的范围

在开启详细日志前,维护者应知道哪些字段可能携带秘密,是否存在自动上传,以及谁能访问输出。诊断开关结束后应关闭,并清理不再需要的副本。用户收到“请开启全部调试并发给我们”的要求时,可以先问能否只保留错误类别、时间和配置标识。若确实必须分享局部参数,应使用正式的私密渠道与明确的脱敏办法。

不要让诊断信息长期留在公开问题页面。即使某条旧请求已经失去时效,日志里仍可能有可重复使用的凭证、账户标识或个人数据。时间窗口过了并不意味着整份文件自动变成无敏感内容。

先判断问题由谁能够修复

使用托管产品的人通常不能修复服务器校时、签名库或参数序列化。这时用户应提供可定位证据并要求提供方处理,而不是承担无限次改账户设置的任务。自行维护程序的人则需要查自己的实现和当前官方说明,不宜把代码里的签名错误直接描述成平台账户故障。

如果确实需要平台支持,先把维护方已验证的项目、错误类别与时间范围整理清楚。平台能够调查实际收到的请求,并不意味着应在工单里主动发送私钥。把职责分开后,用户才能知道谁是下一步行动者,而非在两个客服之间重复粘贴同一张截图。

把修复变成维护记录

最终记录应描述真实找到的原因,例如某个进程没有加载新凭证、某个队列过早固定时间戳,或某次升级改变了参数处理。只有确实取得证据后才能填写这些结论;否则写“已恢复,原因尚未确认”更准确。恢复和根因确定可以是两个不同状态。

同时写下改动范围与验证过的触发条件。以后再次出现类似代码时,先重新收集当次证据,不要因为上次是时钟问题就直接照做。相同错误类别不保证同一原因,保留过程比记住一个万能修复按钮更有价值。

两个用户报告相同代码,如何避免混案

如果服务方同时收到多位用户报错,应先按时间、运行节点、版本和环境分组,而不是把所有问题归为一个原因。一个用户可能刚完成钥匙迁移,另一个可能刚经历后台任务排队;代码相同只是初步类别。对用户而言,提供自己的可定位时间段已经有用,不必索取其他客户的账户信息进行比较。

维护者可以用脱敏任务标识串联内部日志,确认哪条响应属于哪次尝试。讨论结果时只公开通用修复与受影响范围,不应为了证明调查充分而展示客户凭证或私人数据。把问题分组做清楚,反而能减少每位用户被要求重复重建钥匙的次数。

没有发现根因时怎样写结论

若故障已经停止但无法解释原因,可以准确记录恢复时间、期间改动和未验证假设,再决定需要观察的正常场景。不要将猜测写成已证实的系统缺陷,也不要为了结束工单编造一次成功测试。后续再次发生时,这份未决记录能够帮助比较条件;一条过度确定却错误的结论,则可能把下一次排查带向错误方向。

检查我需要的权限 ↗

继续阅读

04 / TROUBLESHOOT

API 连不上:-2015、-1021、-1022 和 429 分别查什么

区分密钥或 IP 问题、时间问题、签名问题与请求限速,避免靠全开权限反复试错。

阅读指南
03 / SETUP

HMAC、RSA、Ed25519:先确认工具支持,再选 API 密钥

把算法名称、密钥文件、工具兼容性和迁移计划分开核对,避免换了类型仍无法连接。

阅读指南