下载

WEEX API 错误代码详解：快速修复 40001 至 43011

By: WEEX|2026-07-27 02:15:00

大多数 WEEX API 错误并非字面意思。40009 API validation failed 几乎从不意味着您的密钥无效，通常是因为签名字符串的拼接顺序错误。在确实存在的交易对上收到 40102 Trading pair configuration does not exist，通常意味着您将合约交易对发送到了现货域名。字面解读错误代码只会让十分钟的修复工作变成一下午的折腾。

这是一份关于 WEEX API 错误代码的实用参考，涵盖了实际集成中遇到的问题，并按故障层级而非代码编号进行分组。下方所有代码均基于 2026 年 7 月 27 日发布的 WEEX API 错误代码列表；签名、时序和速率限制规则基于同期的 WEEX 现货 API 文档。两者均会更新，请在发布前重新核对。

首先进行澄清，因为搜索结果中常有混淆：本文讨论的是 WEEX 加密货币交易所 API（api-spot.weex.com 和 api-contract.weex.com）。它与 Apache Weex 无关，后者是已退役的阿里巴巴移动 UI 框架，共享名称并返回如 -1001 的错误。如果您的堆栈跟踪中提到 WXSDKInstance，则说明您找错了手册。

WEEX API 错误代码的分组方式

官方列表是一个扁平的表格。实际上，这些代码分为七个诊断层级，了解层级即可知道应检查哪个文件。这种分组是缩短调试时间的最快方法，因为 1–4 层通常是您的客户端问题，而第 7 层则完全不是您的错误。

层级	代码	实际故障点	优先检查项
1. 标头缺失	40001, 40002, 40003, 40011	必需的标头未从客户端发出	HTTP 客户端配置
2. 凭据有效性	40006, 40009, 40012, 40016	密钥、密码短语或 2FA 状态错误	API 管理页面
3. 签名与时间	40005, 40007, 40008	预哈希字符串、时钟或 Content-Type	签名函数
4. 账户与权限	40013, 40014, 40018	账户冻结、权限缺失、IP 不在白名单	密钥权限
5. 请求格式	40102, 40305, 40409, 40704, 40707, 40724, 40912, 40913, 41101	参数或交易对与端点不匹配	端点规范
6. 订单引擎	42002, 43001–43011	余额或产品限制导致订单被拒	产品限制与余额
7. 平台与限流	429, 40015, 40200, 40725	服务器端问题；重试，无需重写	退避逻辑

实用规则：如果代码以 400 开头，怀疑您的请求。如果以 43 开头，怀疑您的订单参数。如果是 429、40200 或 40015，不要怀疑任何东西，直接退避。

WEEX API 身份验证错误：40001 至 40018

这一区间产生的支持工单最多，但真正的凭据问题最少。其中六个代码可以通过修复标头构建方式解决，而非生成新密钥。

代码	消息	实际原因	修复方法
40001	The request header 'ACCESS_KEY' cannot be empty	标头被代理或将未知标头小写并丢弃的客户端库剥离	记录发出的标头，而非设置的标头
40002	The request header 'ACCESS_SIGN' cannot be empty	在请求对象冻结后计算签名	在发送前签名
40003	The request header 'ACCESS_TIMESTAMP' cannot be empty	生成了时间戳但未附加	附加与签名时相同的值
40005	Invalid ACCESS_TIMESTAMP	使用了秒而非毫秒，或 ISO 字符串	发送 13 位毫秒时间戳
40006	Invalid ACCESS_KEY	密钥格式错误	WEEX API 密钥以 `WEEX` 开头 — 检查是否误粘贴了密钥
40007	Invalid Content_Type, please use 'application/json'	客户端默认使用 `application/x-www-form-urlencoded`	在 POST 请求中显式设置 `application/json`
40008	Request timestamp has expired	请求超过 30 秒有效期	见下一节 — 这与 40005 是不同的错误
40009	API validation failed	签名不匹配，通常是预哈希顺序错误	精确重建预哈希字符串
40011	The request header 'ACCESS_PASSPHRASE' cannot be empty	因文档将其列在最后而忽略了密码短语	在每个私有调用中包含它
40012	Incorrect API key/passphrase	密码短语拼写错误，或使用了不同子账户的密钥	重新生成并重新输入两者
40013	User account is frozen	账户级暂停	提交支持工单
40014	Insufficient permissions	密钥范围不包含交易或提现	使用正确的范围重新签发密钥
40016	Users must bind a mobile phone or Google Authenticator	未设置 2FA 导致 API 访问受限	启用 Google Authenticator
40018	Illegal IP request	调用 IP 不在白名单中	见下方的基础域名与 IP 节

有两个细节值得铭记。WEEX 签名构建规则定义预哈希字符串为 timestamp + method.toUpperCase() + requestPath + "?" + queryString + body，使用您的密钥进行 HMAC-SHA256 加密，然后进行 Base64 编码。当没有查询字符串时，? 和查询字符串会被省略。生产环境中常导致失败的三点：小写的 get、包含主机的请求路径，以及 HTTP 库在签名后重新序列化的 JSON 正文——键顺序改变、字节改变，导致 40009。

第二个细节是命名陷阱。错误文本引用的标头名称带有下划线（ACCESS_KEY, ACCESS_SIGN, ACCESS_TIMESTAMP, ACCESS_PASSPHRASE），而签名文档中则使用连字符（ACCESS-SIGN, ACCESS-TIMESTAMP）。请复制您正在集成的端点文档中使用的格式，并在首次成功调用时记录原始网络标头，不要盲目信任错误字符串或博客片段。

40005 与 40008：两种不同的时间戳错误

这两个错误常被混淆，错误的修复方式最浪费时间。

40005 Invalid ACCESS_TIMESTAMP 是一个格式问题。该值不是 13 位毫秒时间戳——通常是 Python 中 time.time() 或 PHP 中 time() 返回的 10 位秒级时间戳，或者是 ISO-8601 字符串。它在每次请求（包括第一次）时都会持续失败。

40008 Request timestamp has expired 是一个时钟或延迟问题。格式正确，但该值与 WEEX 服务器时间偏差超过 30 秒。请求仅在 30 秒内有效，如果时间戳与 API 服务器时钟偏差超过 30 秒，签名将被拒绝——机器运行过快或过慢都会导致失败。

症状	可能代码	根本原因	修复方法
从第一次调用开始 100% 失败	40005	单位或类型错误	将秒乘以 1000，以整数形式发送
开发环境正常，容器或虚拟机中失败	40008	宿主机时钟漂移，镜像中无 NTP	同步 NTP，或轮询公共服务器时间端点并缓存偏移量
仅在负载高或重试时失败	40008	时间戳仅生成一次，在重试队列中重复使用	每次重试重新签名，切勿重放已签名的请求
仅在长时间运行的批处理作业中失败	40008	时间戳在作业开始时创建，请求在几分钟后发送	在发送时生成时间戳

容器内的时钟漂移是导致“昨天还能用”的集成失败的最常见原因。如果您无法控制宿主机的 NTP，请在启动时轮询服务器时间端点，存储差值，并在每次签名时将其加到本地时钟上。

-- 价格

订单拒绝：43001 至 43011 和 42002

身份验证通过后，失败会转移到撮合引擎。这些代码修复成本低但忽视代价大，因为在紧密循环中重试被拒订单的机器人会触发限流，从而掩盖真正的问题。

代码	消息	检查内容
42002	BALANCE NOT ENOUGH	账户类型中的余额 — 现货资金无法覆盖合约订单
43001	Order does not exist	来自不同账户类型的订单 ID，或已成交并清除
43002	Order placement failed	通用拒绝；记录完整请求并根据产品限制检查价格和数量
43004	There are no open orders to cancel	对空订单簿执行全撤单；视为良性，非错误
43005	Exceeds maximum order size	该产品的单笔订单上限
43006	Order quantity is less than minimum trading amount	与产品端点的 `minTradeAmount` 进行比较
43007	Order quantity exceeds the maximum trading amount	同上，上限值
43008 / 43011	Current order price cannot be less than 0	负数或未解析的价格字段
43009	Current order price exceeds the limit	价格超出允许范围
43010	Trade amount cannot be less than 0	负数或未解析的数量字段
40912	Single cancellation cannot exceed 50	将批量撤单拆分为 50 个一组
40913	Either orderId or clientId must be provided	提供一个标识符；两者都不发送是条件代码中的隐蔽错误
40305	client_uid length should not exceed 40 characters	修剪您的客户端订单 ID 并去除特殊字符

让资深交易者栽跟头的是 40704 Only query data for the last three months。通过标准查询端点无法回溯 90 天以上的交易历史，因此任何对账作业都需要在成交发生时进行持久化，而不是假设以后可以重新获取。

触发 WEEX API 429 的原因

访问限制规则默认设置为每秒 10 次请求，除非个别端点另有说明。超过此限制将返回 429 Too Many Requests，错误列表中也显示为“Requesting too frequently”。

该限制的三个特性决定了您的设计方式：

已验证请求按 API 密钥计数，未验证请求按公共 IP 计数。 两个共享一个密钥的机器人共享一个额度。同一服务器上使用不同密钥的两个机器人则不共享——但它们的公共市场数据轮询会共享，因为这是按 IP 计数的。
跨多个交易对的批量订单计为一次请求。 文档给出的例子是 4 个交易对 × 10 个订单 = 1 次请求。如果您正在放置网格或重新平衡订单簿，批量处理不是微优化，而是 40 倍的吞吐量差异。
重试计入次数。 在 429 上立即重试的指数退避将使您持续受限。使用抖动进行退避，并丢弃陈旧订单，而不是将它们排队。

实用预算：预留约 60–70% 的限额用于订单流，其余用于余额和仓位轮询，并尽可能将所有内容移至 WebSocket。通过 REST 获取订单簿和行情数据是行为良好的交易机器人被限流的最常见原因。

错误的基础域名与 IP 白名单错误

有两个错误报告得非常糟糕，值得单独列出。

40102 Trading pair configuration does not exist 如果出现在您可以在网站上看到的交易对上，通常不是符号问题。WEEX 将 REST 分为现货的 https://api-spot.weex.com 和合约的 https://api-contract.weex.com。将合约符号发送到现货域名会解析为一个在该域名上确实不存在的交易对，该错误在技术上准确，但极具误导性。在检查符号之前，请先检查主机。

40018 Illegal IP request 意味着调用 IP 不在密钥的白名单中。尴尬的是，以下情况会在您不知情的情况下改变它：云服务商轮换出口 IP、NAT 网关故障转移、VPN 重连，或者在您列入 IPv4 白名单时使用了 IPv6 地址。支持建议是您可以创建一个不绑定 IP 地址的密钥，对于只读市场数据密钥，这是一个合理的权衡。但对于具有交易或提现权限的密钥则不然——未绑定的交易密钥是可以在互联网任何地方使用的凭据。请固定 IP，并监控变化，而不是删除控制。

关于 REST 和 WebSocket 接口如何协同工作的更广泛背景，请参阅 WEEX Wiki 中关于 WEEX 是否支持 API 交易的说明。

5 分钟 WEEX API 分诊检查表

在打开支持工单之前，请按顺序执行此操作。每一步隔离一个层级，第一次失败的地方就是您停止寻找的地方。

时间	检查项	通过条件	失败表现
0:00	在正确域名上调用公共端点，不签名	HTTP 200 并返回数据	连接错误，或域名错误时返回 40102
0:30	打印本地毫秒时间与服务器时间对比	漂移在 5 秒以内	40005（格式）或 40008（漂移）
1:00	记录您签名的确切预哈希字符串	与 `timestamp + METHOD + path + ?query + body` 逐字节匹配	40009
1:30	记录网络上的原始出站标头	所有四个 ACCESS 标头存在，Content-Type 为 application/json	40001, 40002, 40003, 40007, 40011
2:00	调用已签名的只读端点，例如账户余额	HTTP 200	40006, 40012, 40014, 40016, 40018
3:00	获取您交易对的产品端点	返回最小和最大交易额	40102
4:00	放置高于 `minTradeAmount` 的最小合法订单	订单被接受	42002, 43005, 43006, 43007
4:30	检查过去一分钟的请求速率	持续低于每秒 10 次	429

如果每一步都通过但调用仍然失败，剩余的代码（40013, 40015, 40409, 40725, 41101）就是 WEEX 支持明确要求您提交工单处理的代码。请包含请求时间戳、端点和返回的代码；这三者是解决工单的关键。完整的官方参考是 WEEX API 错误代码列表。

错误代码告诉您关于集成的什么

按层级而非频率对失败进行排名。一百个 429 是一个可以在下午调整的吞吐量设计问题。一个间歇性的 40009 是一个会在最糟糕时刻静默丢弃订单的签名错误，这是最值得优先修复的问题。在 WEEX API 上保持健康的集成有三个习惯：每次重试都重新签名，从不信任本地时钟，并记录网络请求而不是预期的请求。

准备好构建了吗？在 WEEX API 页面创建并设置您的密钥范围，从针对公共端点的只读密钥开始，只有在您的分诊检查表运行无误后，才添加交易权限。

常见问题解答

1. WEEX API 上的错误 40009 是什么意思？

API validation failed 更多是签名不匹配而非密钥错误。将预哈希字符串重建为 timestamp + METHOD + requestPath + "?" + queryString + body，确认方法为大写，并确保您的 HTTP 库在您签名后没有重新序列化 JSON 正文。

2. 为什么我的 WEEX API 请求在本地正常，但在生产环境中失败并显示 40008？

几乎总是宿主机时钟漂移。签名的时间戳必须在 WEEX 服务器时间的 30 秒内，而容器经常在没有 NTP 的情况下运行。同步宿主机时钟或在启动时缓存公共服务器时间端点的偏移量。

3. WEEX API 的速率限制是多少？

默认值为每秒 10 次请求，除非端点另有说明，已验证调用按 API 密钥计数，未验证调用按公共 IP 计数，如 2026 年 7 月 27 日所记录。超过此限制将返回 429。

4. 我可以使用没有 IP 白名单的 WEEX API 密钥吗？

可以——当 40018 Illegal IP request 阻止您时，WEEX 支持建议创建一个不绑定到 IP 地址的密钥。请将其保留为只读密钥。没有 IP 限制的交易或提现密钥可以在任何地方使用，这会显著降低安全性。

5. 为什么我收到的 40102 错误针对的是一个确实存在的交易对？

您可能调用了错误的基础域名。现货请求发送到 https://api-spot.weex.com，合约请求发送到 https://api-contract.weex.com；在现货主机上使用合约符号会产生此错误。

6. WEEX API 与 Apache Weex 框架相同吗？

不。WEEX 交易所 API 是一个 REST 和 WebSocket 交易接口。Apache Weex 是一个已停用的移动 UI 框架，具有不相关的错误代码，如 -1001。搜索“weex api”会将两者混淆。

风险提示

加密资产波动剧烈，手动或通过什么是合约 API？如何调用并确保其安全性进行交易可能导致资金部分或全部损失。自动化交易增加了手动交易没有的故障模式：未处理的错误代码可能导致仓位未平或重复，限流撤单可能在成交发生时失败，时钟漂移可能静默拒绝风险对冲订单，且没有 IP 限制或范围限制的 API 密钥是攻击者可以在任何地方使用的凭据。WEEX 上的合约交易涉及杠杆，这会放大收益和损失，并可能比机器人反应更快地触发清算。请使用最小合法订单大小进行测试，在错误处理得到验证之前使用只读密钥，在交易逻辑之外设置仓位和损失限制，切勿向不需要的密钥授予提现权限。此处内容不构成投资建议。

免责声明：本内容仅用于一般品牌传播与信息说明之目的，不构成任何金融、投资、法律或税务建议。文中提及的活动、奖励、线上活动或相关信息，不应被视为对购买、出售、交易任何加密资产，或使用任何服务的推荐、招揽或邀请。加密资产具有高波动性，并存在价值损失风险。WEEX 服务及线上活动的可用性可能因地区而异，并受当地适用法律法规及用户资格要求限制。部分活动可能不适用于某些司法辖区。您有责任确保访问及使用 WEEX 服务符合当地适用法律法规。在参与任何涉及加密资产的活动前，请充分评估相关风险。