跳转到内容
API 参考已发布

RAILWISE-OS 错误码参考

RAILWISE-OS API 完整错误码列表，包含错误分类、处理建议与调试方法

复核 2026-07-09入门公开可引用RailWise 技术团队
API 参考

RAILWISE-OS 错误码参考

Section titled “RAILWISE-OS 错误码参考”

AI语义标签: #错误码 #API错误 #调试指南 #状态码 #开发者参考

1. 错误响应格式

Section titled “1. 错误响应格式”

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

{
  "code": 400001,
  "message": "请求参数错误",
  "data": {
    "field": "project_name",
    "detail": "项目名称不能为空",
    "suggestion": "请提供有效的项目名称，长度 2-100 字符"
  },
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2026-07-08T12:00:00Z",
    "documentation_url": "https://docs.railwise.cn/os/errors/400001"
  }
}

1.1 错误码结构

Section titled “1.1 错误码结构”

错误码为 6 位数字，结构如下：

┌────────┬────────┬────────┐
│  HTTP  │ 模块   │ 具体   │
│ 状态   │ 标识   │ 错误   │
│  类别  │        │  编号  │
├────────┼────────┼────────┤
│  4/5   │  00    │  01    │
│  位    │  2位   │  2位   │
└────────┴────────┴────────┘


示例: 400001
  4  → 客户端错误 (4xx)
  00 → 通用模块
  01 → 参数错误

1.2 HTTP 状态码与错误码对照

Section titled “1.2 HTTP 状态码与错误码对照”
HTTP 状态码 错误码前缀 说明
400 400xxx 请求参数错误
401 401xxx 认证/授权错误
403 403xxx 权限不足
404 404xxx 资源不存在
409 409xxx 资源冲突
422 422xxx 业务逻辑错误
429 429xxx 请求频率限制
500 500xxx 服务器内部错误
502 502xxx 网关错误
503 503xxx 服务不可用

2. 通用错误 (4000xx)

Section titled “2. 通用错误 (4000xx)”
错误码 说明 常见原因 解决方案
400001 请求参数错误 缺少必填参数、参数类型错误 检查请求参数是否符合 API 文档要求
400002 请求体格式错误 JSON 格式非法、Content-Type 错误 检查请求体是否为合法 JSON
400003 参数值超出范围 数值过大/过小、字符串过长 检查参数值是否在允许范围内
400004 参数格式错误 日期格式错误、ID 格式错误 使用正确的格式（如 ISO 8601）
400005 请求体过大 超过最大限制（5MB） 减少单次请求数据量，分批发送

3. 认证错误 (4010xx)

Section titled “3. 认证错误 (4010xx)”
错误码 说明 常见原因 解决方案
401001 API Key 无效 Key 错误、已撤销、已过期 检查 API Key 是否正确，重新生成
401002 JWT Token 过期 Token 超过有效期 使用 Refresh Token 刷新或重新登录
401003 JWT Token 无效 Token 格式错误、签名错误 检查 Token 是否完整，重新获取
401004 权限不足 当前身份无权访问该资源 检查 API Key/Token 的权限范围
401005 OAuth Client 未授权 Client ID 或 Secret 错误 检查 OAuth 应用配置
401006 账号已禁用 用户账号被管理员禁用 联系管理员恢复账号
401007 登录失败次数过多 触发安全锁定 等待 30 分钟后重试或联系技术支持

4. 权限错误 (4030xx)

Section titled “4. 权限错误 (4030xx)”
错误码 说明 常见原因 解决方案
403001 无权访问项目 不属于该项目成员 申请加入项目或联系项目负责人
403002 无权执行操作 缺少写权限 申请提升权限或使用有权限的账号
403003 数据隔离限制 多租户数据隔离 确认操作的数据属于当前租户
403004 功能未授权 当前套餐不包含该功能 升级套餐或联系商务

5. 资源错误 (4040xx)

Section titled “5. 资源错误 (4040xx)”
错误码 说明 常见原因 解决方案
404001 项目不存在 项目 ID 错误或已删除 确认项目 ID 是否正确
404002 任务不存在 任务 ID 错误或已删除 确认任务 ID 是否正确
404003 监测点不存在 监测点 ID 错误或未创建 先在系统中创建监测点
404004 数据记录不存在 数据 ID 错误或已删除 确认数据 ID 是否正确
404005 报告不存在 报告 ID 错误或已删除 确认报告 ID 是否正确
404006 模板不存在 模板 ID 错误或已删除 确认模板 ID 是否正确
404007 用户不存在 用户 ID 错误或已注销 确认用户 ID 是否正确
404008 设备不存在 设备 ID 错误或已移除 确认设备 ID 是否正确

6. 冲突错误 (4090xx)

Section titled “6. 冲突错误 (4090xx)”
错误码 说明 常见原因 解决方案
409001 项目编号重复 项目编号已存在 使用其他项目编号
409002 监测点编号重复 监测点编号在项目内已存在 使用其他监测点编号
409003 数据重复 同一时间点已存在数据 使用更新接口或先删除旧数据
409004 并发修改冲突 资源被其他用户修改 获取最新数据后重试
409005 任务状态冲突 当前状态不允许该操作 检查任务当前状态

7. 业务逻辑错误 (4220xx)

Section titled “7. 业务逻辑错误 (4220xx)”

7.1 数据校验错误 (4221xx)

Section titled “7.1 数据校验错误 (4221xx)”
错误码 说明 常见原因 解决方案
422101 必填字段缺失 缺少必填字段 检查并补充必填字段
422102 字段类型错误 字段类型不匹配 按文档要求提供正确类型
422103 字段值不合法 枚举值错误、格式错误 使用允许的枚举值或正确格式
422104 关联数据不存在 引用的 ID 不存在 先创建关联数据
422105 数值超出范围 超过业务允许的最大/最小值 调整数值到合理范围

7.2 数据质量错误 (4222xx)

Section titled “7.2 数据质量错误 (4222xx)”
错误码 说明 常见原因 解决方案
422201 坐标值超出合理范围 坐标不在中国境内 检查坐标值是否正确
422202 时间范围错误 测量时间早于项目开始 确认测量时间是否正确
422203 数值突变 与上次测量值差异过大 核实数据或调整突变阈值
422204 逻辑不一致 字段间逻辑关系错误 检查数据一致性
422205 精度不足 数值精度不满足要求 提供足够精度的数值

7.3 项目状态错误 (4223xx)

Section titled “7.3 项目状态错误 (4223xx)”
错误码 说明 常见原因 解决方案
422301 项目已归档 无法修改已归档项目 先取消归档
422302 项目已暂停 无法创建新任务 恢复项目状态
422303 项目未开始 无法写入监测数据 等待项目开始或调整开始时间
422304 任务已逾期 无法更新任务状态 先延长截止日期

8. 频率限制错误 (4290xx)

Section titled “8. 频率限制错误 (4290xx)”
错误码 说明 限制 解决方案
429001 API 请求过于频繁 100 次/分钟 降低请求频率，使用批量接口
429002 数据写入过于频繁 500 条/分钟 合并数据，使用批量写入
429003 报告生成过于频繁 10 次/小时 减少报告生成频率
429004 并发请求过多 50 并发 控制并发数，使用队列
429005 认证请求过于频繁 10 次/分钟 使用缓存的 Token

响应头信息：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720440600
Retry-After: 60

9. 服务器错误 (5000xx)

Section titled “9. 服务器错误 (5000xx)”
错误码 说明 常见原因 解决方案
500001 服务器内部错误 未预期的异常 联系技术支持，提供 request_id
500002 数据库错误 数据库连接异常 稍后重试，如持续请联系技术支持
500003 外部服务错误 依赖服务异常 稍后重试
500004 任务队列错误 消息队列异常 稍后重试
500005 文件处理错误 文件读写异常 检查文件格式后重试

10. 服务不可用错误 (5030xx)

Section titled “10. 服务不可用错误 (5030xx)”
错误码 说明 常见原因 解决方案
503001 服务维护中 系统正在维护 查看状态页面，等待维护完成
503002 服务过载 请求量超出容量 稍后重试，使用指数退避
503003 数据库维护 数据库正在维护 等待维护完成

11. 错误处理最佳实践

Section titled “11. 错误处理最佳实践”

11.1 客户端错误处理框架

Section titled “11.1 客户端错误处理框架”
// TypeScript 错误处理示例
class RailWiseAPIError extends Error {
  constructor(
    public code: string,
    public message: string,
    public data?: any,
    public requestId?: string
  ) {
    super(message);
    this.name = 'RailWiseAPIError';
  }
}


async function handleAPIResponse<T>(response: Response): Promise<T> {
  const data = await response.json();


  if (data.code >= 400) {
    const error = new RailWiseAPIError(
      data.code.toString(),
      data.message,
      data.data,
      data.meta?.request_id
    );


    // 根据错误码分类处理
    switch (true) {
      case data.code >= 401000 && data.code < 402000:
        // 认证错误：刷新 Token 或重新登录
        await refreshToken();
        throw error;


      case data.code >= 429000 && data.code < 430000:
        // 频率限制：读取 Retry-After 后重试
        const retryAfter = response.headers.get('Retry-After');
        await sleep(parseInt(retryAfter || '60', 10) * 1000);
        throw new RetryableError(error);


      case data.code >= 500000 && data.code < 600000:
        // 服务器错误：指数退避重试
        throw new RetryableError(error);


      default:
        throw error;
    }
  }


  return data.data;
}


// 带重试的请求封装
async function requestWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof RetryableError && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 指数退避: 1s, 2s, 4s
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

11.2 日志记录建议

Section titled “11.2 日志记录建议”
// 错误日志记录
function logAPIError(error: RailWiseAPIError) {
  console.error('[RailWise API Error]', {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    timestamp: new Date().toISOString(),
    detail: error.data,
  });


  // 发送到监控系统
  monitoring.captureException(error, {
    tags: { api_error_code: error.code },
    extra: {
      requestId: error.requestId,
      detail: error.data,
    },
  });
}

12. 调试方法

Section titled “12. 调试方法”

12.1 使用 Request ID

Section titled “12.1 使用 Request ID”

每个 API 请求都包含唯一的 request_id，在排查问题时提供给技术支持：

{
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2026-07-08T12:00:00Z"
  }
}

12.2 沙箱环境测试

Section titled “12.2 沙箱环境测试”

建议在沙箱环境测试和调试：

Terminal window
# 沙箱环境 Base URL
https://sandbox-api.os.railwise.cn/v3


# 沙箱环境数据隔离，不影响生产数据

12.3 错误码查询 API

Section titled “12.3 错误码查询 API”
Terminal window
# 查询错误码详细信息
curl -X GET "https://api.os.railwise.cn/v3/errors/400001" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

响应示例：

{
  "code": 200,
  "data": {
    "error_code": "400001",
    "message": "请求参数错误",
    "category": "通用错误",
    "common_causes": [
      "缺少必填参数",
      "参数类型错误",
      "参数值格式错误"
    ],
    "solutions": [
      "检查 API 文档确认必填参数",
      "使用正确的参数类型",
      "参考示例请求格式"
    ],
    "example": {
      "request": {
        "project_name": ""  // 空字符串导致错误
      },
      "correct": {
        "project_name": "宁波绕城高速管廊监测项目"
      }
    }
  }
}

13. 相关文档

Section titled “13. 相关文档”

文档版本: v3.2.0 | 最后更新: 2026-07-08 | API版本: v3

引用与复核把知识带回真实工程判断

引用时保留页面与来源线索；涉及标准条文、阈值、频率和项目结论，请回到现行依据与责任人复核。

查看 Agent 使用规则