错误码

本页汇总平台接口的状态码、返回结构与排查建议。

最重要的一条：HTTP 状态码几乎恒为 200

平台绝大多数接口在业务出错时，HTTP 状态码仍然是 200， 真正的错误信息在 返回体的 code 字段里。

// 请求一个不存在的地址 —— HTTP 状态码是 200，业务码是 404
{ "code": 404, "data": "", "message": "地址:999999不存在，请通过/api/address配置" }

因此判断成败必须看 code，不能只看 HTTP 状态码。

# ✅ 正确
ok = resp.status_code == 200 and resp.json().get("code") == 200

# ❌ 错误 —— 会把业务错误当成功
ok = resp.status_code == 200

一、业务状态码总表

以下状态码均在真实调用中实测得到。

code	message 典型值	含义	可重试	处理建议
200	null / SuccessCode	成功	—	正常处理 data
106	数据长度不一致	设备端返回的数据长度与控制参数模板不匹配	❌	设备型号与控制参数模板不匹配，联系运营方核对
401	AuthError	认证失败（账号或密码错误）	❌	核对账号密码；不要重试
403	Access Denied	无权限（以 HTTP 403 返回）	❌	见下方 403
404	ResourceNotFound	请求的资源不存在（如缺少必填的 deviceId）	❌	核对参数，见下方 404
404	地址:xxx不存在，请通过/api/address配置	控制地址不存在	❌	核对 address 取值，见 address 全量表
500	未知错误 / 内部错误	服务端内部异常	⚠️ 有限次	记录 requestId 与 errorDetail，重试 1~2 次后报障
504	请求超时，请点击右上角 '重新获取设定值'按钮，重新获取数据	向设备索要数据超时（设备离线或响应慢）	✅	先查设备在线状态，稍后重试
504	数据缺失,address:xxx 数据不存在	该地址在设备上无数据	❌	该设备的控制参数模板里没有这个地址

关于 message

message 在成功时可能是 null（业务域名）或 "SuccessCode"（实时/控制域名）， 在失败时是错误描述。部分接口的 message 还可能是一个对象， 例如 单设备在线状态 查不到客户端时：

{
  "code": 200,
  "data": { "status": 0, "version": 2, "type": 1, "description": null, "latest_online_datetime": "" },
  "message": { "code": "CLIENTID_NOT_FOUND", "message": "Client ID not found" }
}

因此解析 message 前请先判断它的类型，不要直接当字符串用。

二、HTTP 状态码

接口在框架层就拒绝请求时，才会返回非 200 的 HTTP 状态码，且返回结构不是统一包装体。

场景	HTTP	返回结构
业务域名接口未携带 Authorization（或凭证无效）	403	{"timestamp":…,"status":403,"error":"Forbidden","message":"Access Denied","path":"/api/station"}
业务域名路径不存在	404	{"timestamp":…,"status":404,"error":"Not Found","message":"No message available","path":"/api/xxx"}
实时控制域名路径不存在	404	{"detail":"Not Found"}
实时控制域名未携带 Authorization	200	正常执行（该域名当前不校验凭证）

未授权返回的是 403 不是 401

业务域名下不带凭证调用时，实际返回的是 HTTP 403 + "message": "Access Denied"。 如果你按 401 来判断「需要重新登录」，会漏掉这种情况 —— 建议对 401 和 403 都做凭证刷新尝试，并对 403 额外提示权限问题。

三、高频问题排查

401 认证失败

单指登录接口返回的 code: 401：

{
  "code": 401,
  "message": "AuthError",
  "data": null,
  "errorDetail": "Bad credentials",
  "success": false
}

可能原因	排查方式
账号或密码错误	核对凭证；注意大小写与首尾空格
账号被禁用	用正确密码仍返回 401 时，联系运营方

登录失败时 HTTP 状态码仍是 200

必须读返回体的 code。见上方「最重要的一条」。

403 无权限

可能原因	排查方式
未携带 Authorization 请求头	抓包确认实际发出的请求头
凭证格式错误	必须是 Authorization: Bearer <token>，Bearer 与 token 之间一个空格
凭证已失效	重新调用 登录接口 换新 token
资源不属于你的账号	用 站点列表 / 设备列表 确认资源在不在你名下

先区分「凭证问题」还是「权限问题」

• 换成刚登录拿到的新 token 就好了 ⇒ 凭证问题
• 换新 token 仍然 403 ⇒ 权限问题，重试无意义，请联系运营方并附上 requestId

404 资源不存在

场景	返回	排查
控制地址不存在	code: 404，message 形如 地址:999999不存在	核对 address，见 address 全量表
查询参数缺失	code: 404，message: ResourceNotFound	核对必填参数（常见于 历史数据 缺 deviceId）
URL 路径拼错	HTTP 404，{"error":"Not Found"}	见下方路径拼写对照

路径里下划线与连字符混用，且无规律

正确写法	常见错误写法
/api/device_status	/api/device-status（这里是下划线）
/api/mqtt-client-status	/api/mqtt_client_status（这里是连字符）
/api/control/mqtt	/api/control/mqtt-status
/api/set-value/flush	/api/set_value/flush（这里是连字符）
/api/set-value	/api/set_value
/api/weather-data/list	/api/weather_data/list
/api/weather-data/avg	/api/weather_data/avg
/api/video-data/list	/api/video_data/list
/api/get-value	/api/get_value

没有统一规律，请以各接口页的「请求地址」为准，逐字复制。

504 请求超时 / 数据缺失

:504 出现在两类场景，处理方式不同：

message 特征	含义	处理
请求超时，请点击右上角…重新获取数据	平台向设备索要数据超时	先查在线状态；设备在线则稍后重试
数据缺失,address:xxx 数据不存在	该地址在这台设备上没有数据	不要重试；该设备不支持这个控制项

读取类接口的耗时预期

带 flush=1 的 读取地址值 与 批量读控制参数 会主动向设备索要数据，耗时明显更长（实测单地址 ~4~5 秒，批量 1~2 秒起）。 请把这类请求的超时设为 30 秒以上，不要用默认的 5~10 秒。

500 服务端内部错误

返回体的 errorDetail 会带出内部异常信息，例如：

{
  "code": 500,
  "message": "内部错误",
  "errorDetail": "No enum constant cc.liangjb.iot.common.constant.GroupTypeEnum.YEAR"
}

可能原因	排查方式
枚举值非法	如 groupType 只能取 HOUR / DAY / MONTH
设备上报数据格式异常	记录 requestId 与设备码，报障

errorDetail 可能包含内部实现细节

该字段有时会带出内部类名、文件路径等实现细节。它只用于报障定位，不应作为业务判断依据。

请求成功但 data 为空

可能原因	排查方式
设备离线	用 单设备在线状态 查 data.status（1 = 在线）
时间范围内无数据	放宽 startTimestamp / endTimestamp
传了不存在的设备码	用 设备列表 核对 code
站点下确实没有设备	站点对象的 deviceCount 为 0
设备刚上线	需要等一个上报周期

传错设备码不会报错，只会返回空数组

/api/sensor-data 等接口在设备码不存在时返回 code: 200 + 空数组，不报错。 因此「返回空」不等于「接口正常」—— 请核对设备码后再判断。

控制指令未生效

可能原因	排查方式
设备离线	在线状态；离线时指令无法送达
address 写错	对照 address 全量表
value 取值不对	见 控制设备 · 控制值语义
指定位置类未先切模式	需先下发 10100，再下发 0-100 的开度值
指令已受理但设备未动作	用 读取地址值 flush=1 回读确认

四、报障时需要提供的信息

1. requestId        —— 返回体里的 UUID（最重要）
2. 接口路径与方法    —— 例如 POST /api/set-value
3. 请求时间          —— 精确到分钟
4. 账号 customerId   —— 登录返回的 customerId
5. 涉及的设备/站点    —— deviceCode / stationId
6. 完整请求参数       —— 脱敏后（去掉密码、token）
7. 完整返回报文       —— 原样贴出，含 code / message / errorDetail

切勿在报障信息中包含

• 账号密码
• 完整 token
• 其他客户的业务数据

下一步

• 回到 通用说明 了解返回格式与时间戳约定
• 开始调接口 → 站点列表