错误处理 (Error Handling)

NodeGet 项目的 API 使用统一的错误处理机制，确保所有 RPC 调用都能提供一致的错误响应格式。

错误响应格式

所有 API 错误都遵循 JSON-RPC 2.0 标准 ErrorObject 结构：

{
  "error": {
    "code": <error_code>,
    "message": "<error_message>",
    "data": <optional_error_data>
  }
}

部分命名空间（如 monitoring）会在 data 字段中附带 JsonError 结构（见下方），提供更详细的错误信息；其余命名空间（如 db）的 data 字段为空。

NodegetError 枚举

NodeGet 定义了一个统一的错误枚举 NodegetError，包含以下错误类型：

错误类型

• ParseError(String) - 解析错误（错误码: 101）

  • 当请求数据解析失败时抛出

• InvalidInput(String) - 输入无效（错误码: 108）

  • 当请求参数格式合法但业务上无效时抛出

• PermissionDenied(String) - 权限拒绝（错误码: 102）

  • 当用户没有执行操作的足够权限时抛出

• DatabaseError(String) - 数据库错误（错误码: 103）

  • 当数据库操作失败时抛出

• AgentConnectionError(String) - 代理连接错误（错误码: 104）

  • 当无法连接到代理节点时抛出

• NotFound(String) - 未找到（错误码: 105）

  • 当请求的资源不存在时抛出

• UuidNotFound(String) - UUID 未找到（错误码: 106）

  • 当请求的 UUID 不存在时抛出

• ConfigNotFound(String) - 配置未找到（错误码: 107）

  • 当请求的配置不存在时抛出

• SerializationError(String) - 序列化错误（错误码: 101）

  • 当数据序列化/反序列化失败时抛出

• IoError(String) - IO 错误（错误码: 101）

  • 当输入/输出操作失败时抛出

• Other(String) - 其他错误（错误码: 999）

  • 用于其他未分类的错误

JsonError 结构体

为了统一错误响应格式，NodeGet 使用 JsonError 结构体：

pub struct JsonError {
    pub error_id: i128,           // 错误代码
    pub error_message: String,    // 错误消息
}

错误代码映射

• 101 - ParseError / SerializationError / IoError
• 102 - PermissionDenied
• 103 - DatabaseError
• 104 - AgentConnectionError
• 105 - NotFound
• 106 - UuidNotFound
• 107 - ConfigNotFound
• 108 - InvalidInput
• 999 - Other

非 NodegetError 的 ad-hoc 错误

需要特别说明的是，上面列出的错误码与 NodegetError 枚举只是 NodeGet 项目中统一的错误集合，并非穷尽所有错误码。很多 RPC handler（例如 task、static、KV、crontab、token、js-worker 等命名空间）会在具体业务场景下直接构造 jsonrpsee 的 ErrorObject ，返回项目自定的 code 和 message。这些 ad-hoc 错误码可能与 NodegetError 的取值一致，也可能不一致。客户端在实现错误处理时，除了识别上述通用错误码外，还应以具体响应中的 message 作为业务错误判断依据，而不是仅依赖 code。

错误处理示例

成功响应

{
  "result": {
    // 成功的数据
  }
}

错误响应

{
  "error": {
    "code": 102,
    "message": "Permission denied: Insufficient permissions to read requested task types"
  }
}