错误码说明

版本: v0.1.0 更新日期: 2025-10-03

📋 目录

1. 错误码规范
2. 风控错误 (1xxx)
3. 账户错误 (2xxx)
4. 订单错误 (3xxx)
5. 撮合错误 (4xxx)
6. 系统错误 (5xxx)
7. 结算错误 (6xxx)
8. 服务错误 (9xxx)
9. 错误处理最佳实践

错误码规范

错误响应格式

所有 API 错误响应遵循统一格式：

{
  "success": false,
  "data": null,
  "error": {
    "code": 1001,
    "message": "资金不足，无法开仓"
  }
}

错误码分类

风控错误 (1xxx)

1001 - 资金不足

描述: 账户可用资金不足，无法满足开仓保证金要求

原因:

• 开仓所需保证金 > 账户可用资金
• 预估手续费后资金不足

示例:

{
  "code": 1001,
  "message": "资金不足: 需要 10000.00, 可用 5000.00"
}

解决方案:

1. 减少订单数量
2. 入金增加可用资金
3. 平仓释放保证金

1002 - 超过持仓限额

描述: 超过单品种最大持仓比例限制

原因:

• 单品种持仓占总资金比例 > 配置的最大持仓比例（默认 50%）

示例:

{
  "code": 1002,
  "message": "超过持仓限额: 当前持仓占比 60%, 限制 50%"
}

解决方案:

1. 平仓部分持仓
2. 联系管理员调整持仓限额配置

1003 - 订单金额过大

描述: 单笔订单金额超过限额

原因:

• 订单金额 (价格 × 数量) > 单笔订单最大金额（默认 1000万）

示例:

{
  "code": 1003,
  "message": "订单金额过大: 12000000.00, 限制 10000000.00"
}

解决方案:

1. 拆分订单
2. 使用算法交易（TWAP/VWAP/Iceberg）

1004 - 风险度过高

描述: 账户风险度超过阈值，拒绝下单

原因:

• 风险度 (保证金/权益) > 95%

示例:

{
  "code": 1004,
  "message": "风险度过高: 当前 96%, 限制 95%"
}

解决方案:

1. 立即平仓降低风险
2. 入金增加账户权益
3. 警惕强平风险

1005 - 自成交风险

描述: 检测到潜在的自成交行为

原因:

• 同一用户在同一合约买卖方向相反的订单可能对手成交

示例:

{
  "code": 1005,
  "message": "自成交风险: 存在反向挂单"
}

解决方案:

1. 先撤销反向挂单
2. 检查订单方向是否正确

1006 - 账户不存在

描述: 指定的用户账户不存在

原因:

• 用户未开户
• user_id 错误

示例:

{
  "code": 1006,
  "message": "账户不存在: user_unknown"
}

解决方案:

1. 检查 user_id 是否正确
2. 先调用开户接口创建账户

1007 - 合约不存在

描述: 指定的交易合约不存在

原因:

• instrument_id 错误
• 合约未注册到系统

示例:

{
  "code": 1007,
  "message": "合约不存在: INVALID_CODE"
}

解决方案:

1. 检查 instrument_id 拼写
2. 查询可用合约列表
3. 联系管理员注册新合约

1008 - 订单参数非法

描述: 订单参数不符合规范

原因:

• 订单数量 < 最小数量（默认 1 手）
• 订单数量 > 最大数量（默认 10000 手）
• 价格 <= 0
• 方向/开平标识错误

示例:

{
  "code": 1008,
  "message": "订单数量非法: 0.5 手, 最小 1 手"
}

解决方案:

1. 检查订单参数是否符合要求
2. 参考 API 文档修正参数

账户错误 (2xxx)

2001 - 账户已存在

描述: 开户时用户 ID 已存在

示例:

{
  "code": 2001,
  "message": "账户已存在: user001"
}

解决方案: 使用不同的 user_id 开户

2002 - 账户冻结

描述: 账户被冻结，禁止交易

示例:

{
  "code": 2002,
  "message": "账户已冻结: user001"
}

解决方案: 联系管理员解冻账户

2003 - 入金失败

描述: 账户入金操作失败

示例:

{
  "code": 2003,
  "message": "入金失败: 金额必须大于0"
}

解决方案: 检查入金金额是否合法

2004 - 出金失败

描述: 账户出金操作失败

原因:

• 可用资金不足
• 出金金额非法

示例:

{
  "code": 2004,
  "message": "出金失败: 可用资金不足"
}

解决方案:

1. 检查可用资金余额
2. 减少出金金额

2005 - 持仓不足

描述: 平仓数量大于持仓数量

示例:

{
  "code": 2005,
  "message": "持仓不足: 持有 10 手, 平仓 20 手"
}

解决方案: 减少平仓数量

订单错误 (3xxx)

3001 - 订单不存在

描述: 查询或撤销的订单不存在

示例:

{
  "code": 3001,
  "message": "订单不存在: O12345"
}

解决方案: 检查 order_id 是否正确

3002 - 订单状态不允许撤销

描述: 订单当前状态不允许撤销

原因:

• 订单已成交
• 订单已撤销
• 订单已拒绝

示例:

{
  "code": 3002,
  "message": "订单状态不允许撤销: 已成交"
}

解决方案: 仅撤销状态为 Pending、Accepted、PartiallyFilled 的订单

3003 - 订单提交失败

描述: 订单提交到撮合引擎失败

示例:

{
  "code": 3003,
  "message": "订单提交失败: 撮合引擎繁忙"
}

解决方案: 稍后重试

3004 - 订单修改失败

描述: 订单修改操作失败（预留）

示例:

{
  "code": 3004,
  "message": "订单修改失败: 不支持修改价格"
}

撮合错误 (4xxx)

4001 - 撮合引擎未初始化

描述: 合约的撮合引擎未初始化

示例:

{
  "code": 4001,
  "message": "撮合引擎未初始化: IX2301"
}

解决方案: 联系管理员初始化合约撮合引擎

4002 - 订单簿错误

描述: 订单簿操作失败

示例:

{
  "code": 4002,
  "message": "订单簿错误: 价格档位溢出"
}

解决方案: 报告系统异常

系统错误 (5xxx)

5000 - 内部错误

描述: 系统内部错误

示例:

{
  "code": 5000,
  "message": "内部错误: 数据库连接失败"
}

解决方案: 联系技术支持

5001 - 配置错误

描述: 系统配置错误

示例:

{
  "code": 5001,
  "message": "配置错误: 风控参数非法"
}

解决方案: 联系管理员检查配置

5002 - 存储错误

描述: 数据存储操作失败

示例:

{
  "code": 5002,
  "message": "存储错误: MongoDB 写入失败"
}

解决方案: 联系技术支持

5003 - 序列化错误

描述: 数据序列化/反序列化失败

示例:

{
  "code": 5003,
  "message": "序列化错误: JSON 格式非法"
}

解决方案: 检查请求数据格式

结算错误 (6xxx)

6001 - 结算价未设置

描述: 合约结算价未设置，无法执行结算

示例:

{
  "code": 6001,
  "message": "结算价未设置: IX2301"
}

解决方案: 等待管理员设置结算价

6002 - 结算失败

描述: 账户结算过程失败

示例:

{
  "code": 6002,
  "message": "结算失败: 账户数据异常"
}

解决方案: 联系技术支持

6003 - 强平失败

描述: 强制平仓操作失败

示例:

{
  "code": 6003,
  "message": "强平失败: 市场流动性不足"
}

解决方案: 系统自动重试

服务错误 (9xxx)

9001 - 认证失败

描述: WebSocket 认证失败

原因:

• Token 无效
• Token 过期
• 用户不存在

示例:

{
  "type": "error",
  "code": 9001,
  "message": "认证失败: Token 无效"
}

解决方案:

1. 检查 Token 是否正确
2. 重新登录获取新 Token

9002 - 未认证

描述: 未认证就尝试进行需要认证的操作

示例:

{
  "type": "error",
  "code": 9002,
  "message": "未认证: 请先发送 auth 消息"
}

解决方案: 连接 WebSocket 后先发送 auth 消息

9003 - 消息格式错误

描述: WebSocket 消息格式不正确

示例:

{
  "type": "error",
  "code": 9003,
  "message": "消息格式错误: JSON 解析失败"
}

解决方案: 检查消息 JSON 格式是否正确

9004 - 请求频率过高

描述: API 请求频率超过限制

示例:

{
  "code": 9004,
  "message": "请求频率过高: 限制 100 req/s"
}

解决方案: 降低请求频率或实现客户端限流

9005 - 服务不可用

描述: 服务临时不可用

示例:

{
  "code": 9005,
  "message": "服务不可用: 系统维护中"
}

解决方案: 稍后重试

9999 - 未知错误

描述: 未分类的错误

示例:

{
  "code": 9999,
  "message": "未知错误: 请联系技术支持"
}

解决方案: 联系技术支持并提供错误上下文

错误处理最佳实践

前端错误处理

// 统一错误处理函数
function handleApiError(error: any) {
  const code = error.response?.data?.error?.code;
  const message = error.response?.data?.error?.message;

  switch (code) {
    case 1001: // 资金不足
      return {
        type: 'warning',
        title: '资金不足',
        message: '可用资金不足，请入金或减少订单数量',
        action: '去入金'
      };

    case 1004: // 风险度过高
      return {
        type: 'danger',
        title: '风险警告',
        message: '账户风险度过高，可能触发强平',
        action: '立即平仓'
      };

    case 3001: // 订单不存在
      return {
        type: 'error',
        title: '订单不存在',
        message: '订单可能已撤销或不存在',
        action: null
      };

    default:
      return {
        type: 'error',
        title: '操作失败',
        message: message || '未知错误',
        action: null
      };
  }
}

错误重试策略

// 可重试错误码
const RETRYABLE_ERRORS = [
  5000, // 内部错误
  5002, // 存储错误
  9004, // 请求频率过高
  9005  // 服务不可用
];

async function retryableRequest(
  fn: () => Promise<any>,
  maxRetries = 3,
  delay = 1000
) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error: any) {
      const code = error.response?.data?.error?.code;

      // 不可重试错误，直接抛出
      if (!RETRYABLE_ERRORS.includes(code)) {
        throw error;
      }

      // 最后一次尝试失败
      if (i === maxRetries - 1) {
        throw error;
      }

      // 等待后重试
      await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
    }
  }
}

错误监控和上报

// 错误监控
function reportError(error: any, context?: any) {
  const errorData = {
    code: error.response?.data?.error?.code,
    message: error.response?.data?.error?.message,
    url: error.config?.url,
    method: error.config?.method,
    timestamp: new Date().toISOString(),
    context
  };

  // 上报到监控系统
  if (typeof window !== 'undefined' && window.analytics) {
    window.analytics.track('API Error', errorData);
  }

  // 严重错误发送告警
  if (errorData.code && errorData.code >= 5000) {
    sendAlert(errorData);
  }
}

WebSocket 错误处理

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'error') {
    switch (msg.code) {
      case 9001: // 认证失败
        console.error('认证失败，重新登录');
        // 跳转到登录页
        break;

      case 9002: // 未认证
        // 发送认证消息
        ws.send(JSON.stringify({
          type: 'auth',
          user_id: userId,
          token: token
        }));
        break;

      case 9003: // 消息格式错误
        console.error('消息格式错误:', msg.message);
        break;

      default:
        console.error('WebSocket 错误:', msg);
    }
  }
};

错误码快速查询

文档更新: 2025-10-03 维护者: @yutiansut