错误码表
本页汇总 SDK 返回值中可直接判读的错误码与排查方向。协议层（JSON）的错误码另见 JSON 协议。
Result 枚举（nrc_define.h）
绝大多数操作类接口返回 Result，只有 SUCCESS(0) 表示成功：
| 值 | 枚举 | 含义 | 优先排查 |
|---|---|---|---|
| 0 | SUCCESS | 成功 | — |
| -1 | RECEIVE_FAILED | 接收失败 | 控制器未应答：链路是否通、端口是否正确、控制器是否处于可响应状态 |
| -2 | DISCONNECT | 未连接机器人 | 句柄是否有效、是否取自正确端口（6001/7000 不能混用）、对端是否已断开 |
| -3 | PARAM_ERR | 参数错误 | 数值越界、坐标系/索引非法、结构体未初始化 |
| -4 | OPERATION_NOT_ALLOWED | 操作不允许 | 未上电、模式不符、队列未开启、作业未打开 |
| -5 | EXCEPTION | 异常 | 控制器内部异常，配合日志定位 |
| -6 | TIMEOUT | 超时 | 网络中断、控制器负载过高、单次指令量过大 |
定义与结构体说明见数据结构定义。
非 Result 返回值
| 接口 | 返回 | 判定 |
|---|---|---|
connect_robot | SOCKETFD | 成功返回句柄（≥0），失败返回 -1。失败值不是 Result 的 -1 语义，只表示连接未建立 |
get_library_version | std::string | 版本字符串 |
| 查询类（出参） | Result + 出参 | 必须先判 SUCCESS，再使用出参，避免用到未填充的脏数据 |
两个最常见的误判
-2当成「连接失败」：-2是「未连接」，最常见原因是把 6001 的句柄传给了需要 7000 的接口（如servoJ）。- 用「非 -1 就是成功」判断：
-3/-4/-6都会让业务逻辑静默失败，必须统一按== SUCCESS判断。
排查顺序
- 看码：先按上表定位类别（链路 / 句柄 / 参数 / 状态 / 超时）。
- 看前置：接口说明 · 调用前自检 的连接、伺服状态、模式三项。
- 看日志：控制器侧日志与上位机收发日志对照时间点。
- 复现：固定输入重试一次，确认是稳定失败还是偶发；偶发优先查链路与负载。
各接口的 -4 常见原因
-4（OPERATION_NOT_ALLOWED）没有二级错误码，但按接口族可以快速缩小范围：
| 接口族 | 典型前置条件 |
|---|---|
上下电（set_servo_state / set_servo_poweron） | 存在未清除的报警（状态 2）时不允许；set_servo_state 只在伺服状态 0（停止）或 1（就绪）时生效 |
运动（robot_movj / robot_movel 等） | 未上电（状态 ≠ 3）、当前模式不符（示教 / 运行 / 远程）、已有运动在执行 |
队列（queue_motion_*） | 队列模式未开启；机器人未停止；size 超过队列长度会返回 -3 而不是 -4 |
作业（job_*） | 作业未打开、作业正在运行、插入行号越界 |
参数/工艺写（set_*） | 需先进入对应模式或先使能（如焊接使能 weld_set_enable） |
以上是按接口语义归纳的常见前置，具体判定以控制器实现为准（
[待核]）。
待核
connect_robot失败按文档返回-1。现场遇到的-2（DISCONNECT）通常是句柄 / 端口用错（把 6001 的句柄传给了 servoJ 这类只认 7000 的接口，或对端已断开），不是连接失败；若确认没连上却拿到-2，请记录调用顺序与句柄来源后反馈。- 各接口在
-4（操作不允许）下的细分原因没有独立错误码，需要结合控制器日志判断。 - JSON 协议错误码与 SDK
Result不是一一对应，混用时不要直接映射。