Skip to main content

V3 统一错误码

调用 V3 接口失败时，先看响应体的 code 字段。code = 0 表示成功；非 0 时是固定六位的云端统一错误码，含义与 HTTP 状态无关。本页列出全部分段规则、已定义的错误码和排查建议。

统一错误响应​

V3 业务错误一律返回 HTTP 200 OK，故障信息收敛在 JSON 信封中：

{
  "code": 210002,
  "msg": "Robot is offline.",
  "traceId": "35de92dd84f14097a383a323dee1e6e1",
  "data": {}
}
字段说明
code云端统一错误码。只有 0 表示成功。
msg面向开发者的英文提示，用于快速定位问题，不要依赖它做程序判断。
traceId本次请求的追踪 ID。提单或反馈问题时请一并提供。
data业务数据。失败时固定为 {}，不携带任何业务字段。
失败时 data 一定是空对象

code != 0 的响应里没有 data.cmdResultCode 之类的诊断字段，失败原因只能从 code 和 msg 读取。车端 10 位错误码只出现在成功响应里，见下方「车端错误码与指令状态」。

不要用 HTTP 状态码判断业务成败

业务失败同样返回 200，必须解析响应体的 code。只有网关层拦截（如 401、404、429）才会使用非 200 的 HTTP 状态码。

分段速查​

所有 V3 错误码按业务域分段，看到前两位就能判断问题归属：

错误码范围业务域典型场景
0成功调用成功
100000 ~ 109999通用基础设施内部异常、下游调用失败、参数错误、资源不存在、限流、存储异常
110000 ~ 119999认证与安全内部 Token 无效、外部认证缺失或失效、无资源权限
210000 ~ 219999机器人与设备状态机器人不存在、离线、不支持目标任务或指令
220000 ~ 229999地图与空间地图不存在、地图资源不属于指定地图
230000 ~ 239999任务调度与控制组合任务、排班、充电点相关的校验与冲突
800000 ~ 809999历史接口适配层由历史接口的错误码转换而来
900000 ~ 909999历史适配层兜底无法映射的旧错误

号段内不保证连续，未定义的号码当前不会返回。

完整错误码​

通用基础设施（100000 ~ 100999）​

错误码说明常见原因
100000通用内部服务错误未归类的服务端异常，可重试；持续出现请携带 traceId 反馈
100001下游服务调用失败下游超时或响应解码失败
100003请求参数格式或校验失败必填字段缺失、类型不符、枚举值越界、单次数量超上限
100025通用资源不存在请求的机器人、地图、任务等对象不存在或不属于当前账号
100026请求超过限流阈值调用频率过高，请降低并发或增加重试间隔
100027数据存储访问失败数据库读写异常，可重试

认证与安全（110000 ~ 119999）​

错误码说明常见原因
110001内部鉴权 Token 无效内部转发链路的服务身份校验失败，通常由平台侧排查
110002外部认证信息缺失或无效未携带 Authorization、令牌已过期、令牌格式错误
110003认证通过但无资源权限robotSn 未绑定到当前账号，或不属于当前租户
110004Opaque Token 数量达到上限有效令牌已达 10 个，需先吊销不再使用的令牌

机器人与设备状态（210000 ~ 219999）​

错误码说明常见原因
210000机器人不支持目标任务或指令机型能力不符，或软件版本低于 AIO 1.6
210001机器人不存在或不属于当前云环境robotSn 拼写错误，或机器人未绑定到当前账号
210002机器人当前不在线需要在线操作的指令在机器人离线时下发

地图与空间（220000 ~ 229999）​

错误码说明常见原因
220001地图不存在、未绑定或已失效mapId 过期，或地图不属于该机器人
220002地图资源不属于指定地图分区、路径、点位与传入的地图不匹配

任务调度与控制（230000 ~ 239999）​

错误码说明
230001排班机器人不存在或无权限
230002排班计划不存在或已被删除
230003机器人 Columbus 路由信息为空，暂时无法下发
230004排班地图资源（分区、路径、点位）不存在
230005工作模式无法唯一匹配
230006排班执行类型无效，只允许 1（定时）或 2（定量）
230007简化接口传入了未开放的高级配置字段
230008机器人当前站点不存在
230009地图不存在或不属于当前站点
230010mapId 不是 localMapUuid，或两者不一致
230011排班日期格式或日期范围非法
230012排班时间格式或时间范围非法
230013排班开始日期早于当前日期
230014任务运行时或任务子项不存在
230015任务状态不允许当前指令，或任务版本发生冲突
230016组合任务定义不存在或已被删除
230018指定充电点不存在或不属于请求地图
230019当前地图存在多个充电点，但请求未指定目标
230020当前地图没有可用充电点
230021请求地图不存在或无法解析地图名称
排班与充电点的细节

230001 ~ 230013 主要来自排班接口，建议先调用「查询任务资源」确认分区、路径和点位后再构造请求。230018 ~ 230021 来自充电点相关接口，先调用「查询充电桩点位列表」取得可用的充电点标识。

历史接口适配层（800000 ~ 809999）​

调用历史接口或私有云底座时，旧版错误码会被自动转换到 8xxxxx 段返回。收到该段错误码，说明错误源自历史适配层，message 来自原始下游接口，请结合该下游接口自身的错误定义排查，不要按 V3 号段解读。

转换规则属于平台内部实现，此处不展开，也不作为对外契约承诺。下游返回标准 gRPC 状态码时，适配层会按语义统一收敛为对应的 V3 错误码，调用方按 V3 号段处理即可。

历史适配层兜底（900000 ~ 909999）​

错误码说明
900001无法映射的旧错误，默认收敛至此。请携带 traceId 反馈。

车端错误码与指令状态​

机器人侧返回的 10 位错误码不会出现在最外层 code 中，只出现在成功响应（code = 0）的 data 内：

字段说明
data.cmdStatus指令状态。6 表示指令下发成功，7 表示机器人侧执行失败。
data.cmdResultCode原样保留车端 10 位十进制错误码字符串。
data.cmdResultMessage该错误码对应的英文描述；缓存未命中时为空字符串。

指令已投递给机器人但执行失败，仍然属于成功响应。 此时 code = 0、data.cmdStatus = 7，失败原因从 data.cmdResultCode 读取；只有云端自身拒绝请求（参数错误、机器人不在线、无权访问等）才会返回 code != 0，那时 data 为空对象，不再提供车端错误码。调用方要先判断 code，再决定是否解析 data.cmdResultCode。

指令状态有三个容易误判的点：

  • cmdStatus = 6 时固定返回 cmdResultCode = 6880 和 cmdResultMessage = success，只表示指令已成功下发，不代表机器人已完成动作。要确认执行结果，需要继续查询任务或机器人状态。
  • cmdStatus = 7 时 cmdResultCode 才是真实的失败原因，需按车端错误码表解读。
  • cmdStatus 为其他值时 cmdResultCode 可能为空，此时尚未产生执行结果，需继续查询指令状态。

任务启动阶段的失败码（形如 20101000xx 的 10 位码）是车端业务码，统一在「任务启动失败错误代码」中查阅，不要与云端六位码混淆。

HTTP 状态码与业务码的对应​

网关层在业务路由之外拦截请求时，会直接使用标准 HTTP 状态码，此时响应可能没有 V3 信封：

HTTP 状态码含义处理方式
400请求报文损坏或强制 Header 缺失检查 JSON 是否截断、Content-Type 是否正确
401未携带令牌或签名校验失败重新获取 access_token
403身份合法但无接口调用权限确认账号角色与接口权限
404请求路由不存在检查 URL，V3 业务接口以 /openapi/v3/ 开头
429触发限流降低并发，按退避策略重试
500 / 502 / 504网关内部错误或后端失联稍后重试；持续出现请提供 traceId

排查顺序​

  1. 先看 code，不看 HTTP 状态码。HTTP 200 也可能是业务失败。
  2. 按号段定位归属。1xxxxx 是平台与认证，2xxxxx 是机器人与业务，8xxxxx / 9xxxxx 是历史适配层。
  3. 110003 先查绑定关系。多数「无权限」是 robotSn 不属于当前账号，而不是令牌问题。
  4. 100003 对照字段说明。重点检查必填、枚举范围、单次数量上限和数组元素结构。
  5. 异步指令要等结果。code = 0 只代表请求被接受，需用 requestId 查询指令状态或记录。
  6. 反馈问题时附上 traceId。它能把云端日志与本次请求对应起来。

相关页面：查询机器人列表、查询机器人当前状态快照、查询指令状态、查询指令记录、任务启动失败错误代码。