Hyperliquid项目中的随机"User or API does not exist"错误分析与解决方案

Hyperliquid项目中的随机"User or API does not exist"错误分析与解决方案

在Hyperliquid项目开发过程中，开发者可能会遇到一个看似随机的错误提示："L1 error: User or API Wallet 0x... does not exist"。这个错误并非总是出现，而是在某些特定条件下才会触发，给开发者带来了不少困扰。

错误现象

开发者在使用WebSocket创建订单时，会随机收到如下错误响应：

{
  "channel": "post",
  "data": {
    "id": 1740172698150,
    "response": {
      "type": "action",
      "payload": {
        "status": "err",
        "response": "L1 error: User or API Wallet 0xcd9de27135a4e0826525509178e97d592f24ef5a does not exist."
      }
    }
  }
}

值得注意的是，错误信息中的钱包地址每次都会变化，而且这个错误是随机出现的，有时请求能成功执行，有时则会失败。

根本原因分析

经过深入调查，发现这个错误实际上是由两个关键因素导致的：

1. 参数顺序问题：在使用signL1Action函数直接签名（而不通过类封装）时，action对象中各个键(key)的顺序会直接影响action哈希值的生成，进而影响签名结果。Hyperliquid的签名验证对参数顺序有严格要求。

2. 数值格式化问题：Hyperliquid API对价格('p')和数量('s')字段有特殊要求：

   • 不允许包含尾随零(trailing zeros)
   • 例如：12345.0需要简化为12345
   • 0.123450需要简化为0.12345

当这两个条件中的任何一个不满足时，系统不会直接指出具体的格式错误，而是会返回"User or API Wallet does not exist"这样令人困惑的错误信息。

解决方案

要彻底解决这个问题，开发者可以采取以下措施：

1. 使用类封装：建议使用项目提供的类来格式化请求，而不是直接调用signL1Action函数。类封装会自动处理参数顺序和数值格式化问题。

2. 手动格式化数值：如果必须直接使用signL1Action函数，需要确保：

   • 价格和数量字段不包含任何尾随零
   • 使用Number()或类似方法去除不必要的零
   • 例如：将123.450转换为123.45

3. 参数顺序一致性：确保action对象中的参数顺序与API文档要求完全一致，避免因顺序不同导致的签名验证失败。

最佳实践

为了避免类似问题，建议开发者在与Hyperliquid API交互时遵循以下最佳实践：

1. 始终使用项目提供的封装类和方法，而不是直接构造请求
2. 在发送请求前，对数值参数进行规范化处理
3. 实现请求参数的验证逻辑，确保符合API要求
4. 对于关键操作，添加适当的错误处理和重试机制

通过遵循这些指导原则，开发者可以避免"User or API does not exist"这样的错误，确保与Hyperliquid API的交互更加稳定可靠。