错误代码

HashNut API 使用标准化错误代码来指示不同类型的错误。本文档提供全面的错误代码参考，包括含义、常见原因和解决步骤。

响应格式

错误响应结构

{
  "code": -2,
  "msg": "错误消息描述",
  "data": null
}

响应字段

字段	类型	描述
`code`	integer	错误代码（0 = 成功，非零 = 错误）
`msg`	string	人类可读的错误消息
`data`	object/null	错误详情（错误时通常为 null）

API 响应错误代码

成功代码

`0`: 成功 ✅

含义：请求处理成功
常见原因：不适用（成功状态）
解决步骤：不适用
示例响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
    "merchantOrderId": "e30ff306-5552-497d-9083-fd6e943dfd73"
  }
}

认证和授权错误

`-2`: 签名/凭据无效 ✅ 已记录

含义：认证或签名验证失败。请求签名无效、凭据不正确或缺少必需的认证请求头。
常见原因：
- API 签名无效（用于签名的 apiKey 不正确）
- accessKeyId 无效（未找到商户访问密钥 ID 或未激活）
- 缺少必需的请求头（hashnut-request-uuid、hashnut-request-timestamp、hashnut-request-sign）
- 签名算法实现不正确
- 商户账户的货币/链组合无效
- 请求体中缺少或无效的必需字段
- API 凭据未激活或已过期
- IP 地址限制（如果启用了 IP 绑定）
解决步骤：
1. 验证 apiKey 是否正确，并与用于签名生成的密钥匹配
2. 验证 accessKeyId 是否正确，并在 Hashnut 仪表板中处于活动状态
3. 检查所有必需的请求头是否存在且格式正确
4. 验证签名生成算法是否与文档匹配（HMAC-SHA256，Base64 编码）
5. 确保请求体 JSON 字符串与签名的内容完全匹配（无额外空格，字段顺序正确）
6. 验证链/货币组合是否支持您的商户账户
7. 检查 API 密钥是否已过期或已停用
8. 如果启用了 IP 绑定，请验证您服务器的 IP 地址是否在白名单中
9. 如果确认凭据正确但错误仍然存在，请联系 Hashnut 支持
示例响应：

{
  "code": -2,
  "msg": "Invalid signature or credentials",
  "data": null
}

`-1`、`-3`、`-4`：认证错误 ⚠️ 待确认

含义：[待 Hashnut 团队记录]
状态：这些错误代码已保留，但含义需要 Hashnut 支持团队确认
操作：如果遇到这些代码，请联系 Hashnut 支持

验证错误

`-10`、`-11`、`-12`：参数验证错误 ⚠️ 待确认

估计含义：参数验证错误（可能是缺少必需字段、格式无效或类型不匹配）
状态：错误代码已保留，但确切含义需要确认
常见场景（估计）：
- 请求体中缺少必需字段
- chainCode 或 coinCode 格式无效
- amount 格式或值无效
- merchantOrderId 格式无效
- 回调 URL 格式无效
解决步骤（一般）：
1. 验证所有必需字段是否存在
2. 检查 chainCode 和 coinCode 是否有效（使用配置端点）
3. 确保 amount 是有效的小数（2 位小数）
4. 验证 merchantOrderId 是唯一的且在长度限制内（255 个字符）
5. 确保回调 URL 是有效的 HTTPS URL

订单和支付错误

`-20`、`-21`、`-22`、`-23`、`-24`：订单/支付错误 ⚠️ 待确认

估计含义：
- -20：订单创建错误
- -21：重复的 merchantOrderId
- -22：金额无效
- -23：不支持的链/代币
- -24：订单未找到
状态：错误代码已保留，但确切含义需要确认
解决步骤（一般）：
- 验证订单 ID 是否正确
- 检查订单是否创建成功
- 确保使用正确的环境（测试网 vs 生产环境）
- 为每个订单使用唯一的 merchantOrderId
- 验证链/代币组合是否受支持

速率限制和配额错误

`-30`、`-31`：速率限制错误 ⚠️ 待确认

估计含义：超过速率限制或配额
状态：错误代码已保留，但确切含义需要确认
解决步骤：
1. 检查您的 API 使用情况是否超过速率限制
2. 为重试实现指数退避
3. 如果需要，请联系 Hashnut 支持以增加速率限制

系统和服务器错误

`-50`、`-51`、`-52`：系统错误 ⚠️ 待确认

估计含义：
- -50：内部服务器错误
- -51：服务不可用
- -52：数据库错误
状态：错误代码已保留，但确切含义需要确认
解决步骤：
1. 使用指数退避重试请求
2. 检查 Hashnut 服务状态
3. 如果错误仍然存在，请联系 Hashnut 支持

业务逻辑错误

`-60`、`-61`、`-62`：业务逻辑错误 ⚠️ 待确认

估计含义：
- -60：违反业务规则
- -61：余额/资金不足
- -62：账户限制
状态：错误代码已保留，但确切含义需要确认
解决步骤：
1. 查看业务规则和账户状态
2. 验证账户是否有足够的权限
3. 对于账户相关问题，请联系 Hashnut 支持

网络错误

HTTP 状态代码

状态代码	描述	解决方案
`200`	成功	请求处理成功
`400`	错误请求	检查请求参数
`401`	未授权	验证认证凭据
`500`	内部服务器错误	重试请求或联系支持

错误处理最佳实践

1. 始终检查响应代码

const response = await fetch(url, options);
const result = await response.json();

if (result.code !== 0) {
  // 处理错误
  console.error('API Error:', result.msg);
  handleError(result.code, result.msg);
} else {
  // 处理成功
  processData(result.data);
}

2. 实现重试逻辑

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const result = await response.json();
      
      if (result.code === 0) {
        return result;
      }
      
      // 对临时错误重试
      if (shouldRetry(result.code) && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000); // 指数退避
        continue;
      }
      
      throw new Error(result.msg);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

function shouldRetry(code) {
  // 对临时错误重试（系统错误、速率限制），不对认证/验证错误重试
  // 系统错误（-50 到 -52）和速率限制（-30 到 -31）可以重试
  return code <= -30 && code >= -52;
}

3. 提供用户友好的消息

function getErrorMessage(code, msg) {
  const errorMessages = {
    '0': '成功',
    '-2': '认证失败。请检查您的 API 凭据。',
    '-10': '验证错误。请检查您的请求参数。',
    '-11': '缺少必需字段。请验证所有必需参数是否已包含。',
    '-12': '参数格式无效。请检查参数类型和格式。',
    '-20': '订单创建失败。请重试或联系支持。',
    '-21': '重复的订单 ID。请使用唯一的 merchantOrderId。',
    '-22': '金额无效。请检查支付金额。',
    '-23': '不支持的链或代币。请验证 chainCode 和 coinCode。',
    '-24': '订单未找到。请验证订单 ID。',
    '-30': '超过速率限制。请减慢您的请求速度。',
    '-31': '超过配额。请联系支持以增加限制。',
    '-50': '内部服务器错误。请重试或联系支持。',
    '-51': '服务不可用。请稍后重试。',
    '-52': '数据库错误。请联系支持。',
    '-60': '违反业务规则。请检查您的账户状态。',
    '-61': '余额不足。请验证账户资金。',
    '-62': '账户限制。请联系支持。',
  };
  
  return errorMessages[code] || msg || '发生意外错误';
}

4. 记录错误以便调试

function handleError(code, msg, context) {
  // 记录带上下文的错误
  console.error('API Error:', {
    code,
    message: msg,
    context,
    timestamp: new Date().toISOString()
  });
  
  // 发送到错误跟踪服务
  errorTrackingService.captureError({
    code,
    message: msg,
    context
  });
}

支付验证错误消息

这些错误消息在支付验证失败时出现在订单响应的 errorMsg 字段中。它们在查询订单状态（queryPayOrderWithAccessSign）时返回，并指示为什么支付交易被拒绝。

`"amount not enough"` ✅ 已记录

含义：收到的支付金额少于所需的订单金额
常见原因：
- 客户发送的金额少于所需金额
- 进行了部分支付
- 客户钱包中的金额计算错误
解决步骤：
1. 检查订单响应中的订单金额与已支付金额
2. 如果 underPaid 为 true，可能有一个补充订单可用于剩余金额
3. 客户应发送确切的剩余金额以完成支付
4. 验证金额是否包含所需的任何网络费用
订单响应中的示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "state": -1,
    "errorMsg": "amount not enough",
    "amount": 0.01,
    "paidAmount": 0.005,
    "underPaid": true
  }
}

`"coin type mismatch"` 或 `"coin type not math"` ✅ 已记录

含义：客户发送了错误的加密货币/代币类型（例如，发送了 USDC 而不是 USDT）
常见原因：
- 客户在钱包中选择了错误的代币
- 客户发送了原生币而不是代币（或反之）
- 代币合约地址不匹配
解决步骤：
1. 验证订单需要正确的 coinCode（例如，"usdt"、"usdc"）
2. 客户必须使用正确的代币类型创建新订单
3. 检查代币合约地址是否与订单要求匹配
4. 确保客户的钱包配置为正确的代币

`"receipt address mismatch"` ✅ 已记录

含义：支付发送到的地址与订单的接收地址不同
常见原因：
- 客户复制了错误的地址
- 客户发送到了不同的商户地址
- 地址在客户钱包中被修改
解决步骤：
1. 验证客户使用了订单中的确切 receiptAddress
2. 检查地址格式是否正确（某些链区分大小写）
3. 客户应在发送前验证地址是否匹配
4. 如果支付发送到错误地址，无法恢复 - 客户必须创建新订单

`"transaction execute failed"` ✅ 已记录

含义：区块链交易执行失败（例如，回退、gas 不足、余额不足）
常见原因：
- 交易 gas/能量不足
- 智能合约执行回退
- 客户钱包中代币余额不足
- 网络拥塞导致交易失败
- 交易被网络拒绝
解决步骤：
1. 在区块链浏览器上检查交易哈希以查看失败原因
2. 验证客户是否有足够的余额（代币 + 用于 gas 的原生币）
3. 确保 gas 限制足以进行交易
4. 客户应使用足够的 gas 重试支付
5. 检查网络状态是否存在拥塞问题

`"can not parse transaction"` 或 `"cannot parse transaction"` ✅ 已记录

含义：系统无法解析或解码来自区块链的交易数据
常见原因：
- 交易格式无效或损坏
- 不支持的交易类型
- 交易数据编码问题
- 区块链节点返回格式错误的数据
解决步骤：
1. 在区块链浏览器上验证交易哈希是否有效
2. 检查交易是否在区块链上确认
3. 联系 Hashnut 支持并提供交易哈希以进行调查
4. 如果无法恢复交易，客户可能需要创建新订单

`"transaction not found"` ✅ 已记录

含义：提供的交易哈希在区块链上找不到
常见原因：
- 交易哈希不正确或无效
- 交易从未广播到网络
- 交易仍在等待中且尚未被索引
- 错误的区块链网络（例如，在测试网上交易但检查主网）
解决步骤：
1. 验证交易哈希是否正确
2. 在链的正确区块链浏览器上检查交易
3. 如果交易刚刚发送，请等待几分钟（可能需要时间才能被索引）
4. 验证正在检查正确的网络/链
5. 如果交易确实不存在，客户应重试支付

支付金额场景

这些是出现在订单响应中的支付状态场景（不是错误代码）：

支付不足 ✅ 已记录

含义：客户发送的金额少于所需的订单金额。系统为剩余金额创建补充订单。
响应中的指示器：
- underPaid: true
- 存在 paidAmount 字段，金额小于 amount
- supplements 数组包含状态为 state: 0（待处理）的补充订单
解决步骤：
1. 检查 paidAmount 与 amount 以查看差异
2. 在 supplements 数组中找到 state === 0 的活动补充订单
3. 客户应向相同的 receiptAddress 支付剩余金额
4. 支付后，使用补充订单的 supplementId 和交易哈希调用 confirmSupplementPaid API

超额支付 / 标志金额 ✅ 已记录

含义：客户发送的金额超过所需金额，或者订单中添加了容差/调整金额（flagAmount）。
响应中的指示器：
- 存在 flagAmount 字段（非零）
- amountString = originalAmountString + flagAmountString
- 支付金额可以是 >= amountString（原始 + 标志）
解决方案：系统接受等于或大于调整后金额的支付

错误代码参考表

代码	状态	类别	重试？	备注
`0`	✅ 已记录	成功	不适用	请求处理成功
`-2`	✅ 已记录	认证	❌ 否	签名/凭据无效
`-1`、`-3`、`-4`	⚠️ 待确认	认证	❌ 否	已保留，需要确认
`-10` 到 `-12`	⚠️ 待确认	验证	❌ 否	参数验证错误
`-20` 到 `-24`	⚠️ 待确认	订单/支付	❌ 否	订单/支付错误
`-30` 到 `-31`	⚠️ 待确认	速率限制	⚠️ 是	速率限制/配额错误
`-50` 到 `-52`	⚠️ 待确认	系统	⚠️ 是	系统/服务器错误
`-60` 到 `-62`	⚠️ 待确认	业务逻辑	❌ 否	违反业务规则

支付验证错误消息

错误消息	状态	备注
`"amount not enough"`	✅ 已记录	支付金额少于所需金额
`"coin type mismatch"`	✅ 已记录	错误的加密货币/代币类型
`"receipt address mismatch"`	✅ 已记录	支付发送到错误地址
`"transaction execute failed"`	✅ 已记录	区块链交易失败
`"can not parse transaction"`	✅ 已记录	无法解析交易数据
`"transaction not found"`	✅ 已记录	找不到交易哈希

订单状态代码

状态代码	状态	备注
`0`	✅ 已记录	未支付 - 订单已创建，等待支付
`1`	✅ 已记录	未完成 - 支付已发起
`2`	✅ 已记录	等待区块链确认
`3`	✅ 已记录	确认中 - 交易已确认
`4`	✅ 已记录	成功 - 支付完成并已验证
`-1`	✅ 已记录	失败 - 支付交易失败
`-2`	✅ 已记录	已过期 - 订单已过期未支付
`-3`	✅ 已记录	已取消 - 订单已被商户取消

故障排除常见错误

"签名或凭据无效"

检查清单：

apiKey 正确
请求体字符串化正确（无空格）
UUID 对每个请求都是唯一的
时间戳以毫秒为单位
所有必需的请求头都存在
签名正确进行 Base64 编码

"参数无效"

检查清单：

所有必需字段都存在
chainCode 有效（使用配置端点验证）
coinCode 有效且区分大小写
amount 是有效的小数（2 位小数）
merchantOrderId 是唯一的
回调 URL 是有效的 HTTPS URL

"订单未找到"

检查清单：

payOrderId 正确
merchantOrderId 与订单匹配
accessSign 来自订单创建响应
使用正确的环境（测试网 vs 生产环境）

获取帮助

如果您遇到本文档中未记录的错误：

检查日志：查看请求/响应日志
验证配置：确保所有设置都正确
使用 cURL 测试：直接使用 cURL 测试 API 调用
联系支持：
- 邮箱：support@hashnut.io
- 包含错误代码、消息和请求详情
- 分享相关日志（不包含敏感数据）

下一步

查看认证以解决签名问题
检查API 端点以了解参数要求
探索故障排除以了解常见问题

需要帮助？ 查看故障排除 →

响应格式​

错误响应结构​

响应字段​

API 响应错误代码​

成功代码​

0: 成功 ✅​

认证和授权错误​

-2: 签名/凭据无效 ✅ 已记录​

-1、-3、-4：认证错误 ⚠️ 待确认​

验证错误​

-10、-11、-12：参数验证错误 ⚠️ 待确认​

订单和支付错误​

-20、-21、-22、-23、-24：订单/支付错误 ⚠️ 待确认​

速率限制和配额错误​

-30、-31：速率限制错误 ⚠️ 待确认​

系统和服务器错误​

-50、-51、-52：系统错误 ⚠️ 待确认​

业务逻辑错误​

-60、-61、-62：业务逻辑错误 ⚠️ 待确认​

网络错误​

HTTP 状态代码​

错误处理最佳实践​

1. 始终检查响应代码​

2. 实现重试逻辑​

3. 提供用户友好的消息​

4. 记录错误以便调试​

支付验证错误消息​

"amount not enough" ✅ 已记录​

"coin type mismatch" 或 "coin type not math" ✅ 已记录​

"receipt address mismatch" ✅ 已记录​

"transaction execute failed" ✅ 已记录​

"can not parse transaction" 或 "cannot parse transaction" ✅ 已记录​

"transaction not found" ✅ 已记录​

支付金额场景​

支付不足 ✅ 已记录​

超额支付 / 标志金额 ✅ 已记录​

错误代码参考表​

支付验证错误消息​

订单状态代码​

故障排除常见错误​

"签名或凭据无效"​

"参数无效"​

"订单未找到"​

获取帮助​

下一步​

响应格式

错误响应结构

响应字段

API 响应错误代码

成功代码

`0`: 成功 ✅

认证和授权错误

`-2`: 签名/凭据无效 ✅ 已记录

`-1`、`-3`、`-4`：认证错误 ⚠️ 待确认

验证错误

`-10`、`-11`、`-12`：参数验证错误 ⚠️ 待确认

订单和支付错误

`-20`、`-21`、`-22`、`-23`、`-24`：订单/支付错误 ⚠️ 待确认

速率限制和配额错误

`-30`、`-31`：速率限制错误 ⚠️ 待确认

系统和服务器错误

`-50`、`-51`、`-52`：系统错误 ⚠️ 待确认

业务逻辑错误

`-60`、`-61`、`-62`：业务逻辑错误 ⚠️ 待确认

网络错误

HTTP 状态代码

错误处理最佳实践

1. 始终检查响应代码

2. 实现重试逻辑

3. 提供用户友好的消息

4. 记录错误以便调试

支付验证错误消息

`"amount not enough"` ✅ 已记录

`"coin type mismatch"` 或 `"coin type not math"` ✅ 已记录

`"receipt address mismatch"` ✅ 已记录

`"transaction execute failed"` ✅ 已记录

`"can not parse transaction"` 或 `"cannot parse transaction"` ✅ 已记录

`"transaction not found"` ✅ 已记录

支付金额场景

支付不足 ✅ 已记录

超额支付 / 标志金额 ✅ 已记录

错误代码参考表

支付验证错误消息

订单状态代码

故障排除常见错误

"签名或凭据无效"

"参数无效"

"订单未找到"

获取帮助

下一步