常见问题

这里按用户接入时最常见的问题组织排查路径。先选择最接近的现象；字段定义、端点参数和完整错误码仍以接口文档为准。

按现象定位

我遇到的问题	从这里开始
还没有 API Key，不知道从哪里创建	调用还没成功
无法获取 token，或请求返回 401 / 403	调用还没成功
设备不在列表中，或状态看起来不是最新的	设备数据不符合预期
想持续监控外设、离线或断电状态	设备数据不符合预期
命令已接受，但设备没有动作或最终超时	设备操作没有按预期完成
WebSocket 连不上、频繁断线或事件有缺口	实时连接不稳定
不确定该用 REST API 还是 WebSocket	REST API 和 WebSocket 如何选择
请求返回 429、503 或网关不可用	请求过多或服务暂不可用
按文档排查后仍无法解决	准备排障信息

调用还没成功

如何创建 API Client 并获取凭证？

在 WLTE 开发者后台创建 API Client。

1. 登录开发者后台：https://developer.svnwi.com/wlte
2. 进入应用，打开 API Client 管理。
3. 创建 API Client，并选择业务需要的最小权限。
4. 保存创建结果中的 clientId 和 clientSecret。

创建 API Client 后会获得 clientId 和 clientSecret，使用这两个凭证获取 access token。

clientSecret 只在创建或轮换时显示，请立即保存到服务端密钥存储。遗失后不能查看原值，需要轮换 secret。参见获取 API Key。

无法获取 access token

按以下顺序检查：

1. API Client 是否存在且已启用。
2. clientId 和 clientSecret 是否属于同一个 Client。
3. 应用和账号是否处于可用状态。
4. 请求地址、方法和请求体是否与创建访问令牌一致。

不要无限重试错误凭证，否则可能触发认证限流。

请求返回 AUTH_INVALID

凭证或凭证对应的主体当前无效。常见原因是凭证错误、API Client 已停用或删除、应用已停用、账号状态无效。

如果刚轮换过 secret，请确认使用的是新 secret。客户端应基于 code 处理错误，不要依赖 message。

请求返回 AUTH_SCOPE_DENIED

当前 API Client 没有端点需要的权限。响应中的 data.requiredScope 会指出缺少的权限。

在开发者后台增加该权限，保存后重新获取 token，再重试请求。端点所需权限参见权限范围。

停用或删除 API Client 后，旧 token 还能使用吗？

不能。受保护接口会检查 API Client、应用和账号的当前状态，而不只检查 JWT 是否过期。

停用或删除后，新 token 无法签发，已签发 token 也会被拒绝。

可以在网页或移动 App 中保存 clientSecret 吗？

不可以。clientSecret 是服务端凭证，客户端安装包、浏览器资源和日志都无法可靠保护它。

凭证应保存在你控制的服务端。不要把 clientSecret、access token 或 WebSocket ticket 写入前端代码、公开仓库和日志。

设备数据不符合预期

设备没有出现在设备列表中

先确认设备已添加到当前账号，并且 API Client 有权访问该设备。

如果开发者后台能看到设备，但 API 返回为空，检查 Client 的设备授权范围和 device:read 权限。仍无法确认时，记录 requestId 后联系支持。

设备列表中的状态不是刚刚看到的物理状态

设备列表返回平台已同步的设备状态，不会为每一条列表请求主动刷新所有物理设备。它适合列表页、看板和批量读取。

用户明确刷新或操作前后需要最新状态时，使用查询设备详情或 WebSocket 状态请求。

可以高频轮询 HTTP 获取外设、离线或断电状态吗？

不建议。外设状态、离线状态、断电事件都属于实时性较强的数据，用 HTTP 高频轮询会放大设备刷新压力，也更容易触发限流。

推荐做法：

1. 设备列表页、看板和后台同步使用 查询设备列表。
2. 单台设备详情页由用户点击刷新时，使用 查询设备详情 或 WebSocket device.state.get。
3. 需要持续感知离线、断电、外设变化时，建立 WebSocket 连接并订阅设备事件；断线重连后再用 HTTP 或 device.state.get 重新确认关键状态。

不要对每台设备每几秒调用一次实时刷新接口。这样既不能保证事件不丢失，也会影响同账号下其他正常请求。

deviceType 返回 UNSUPPORTED

平台尚未为该设备提供可使用的设备类型定义。设备可能仍属于当前账号，但客户端不应假设其状态结构或控制能力可用。

不要根据设备 ID 前缀自行推导能力。

如何判断设备能否执行某个操作？

查询设备类型定义列表，检查 capabilities.supportedOperations。

只有其中列出的操作才应展示或调用。例如没有 device.rs485.transceive 时，不应显示 RS485 透传入口。

设备操作没有按预期完成

返回 COMMAND_ACCEPTED，但设备还没有动作

COMMAND_ACCEPTED 只表示平台接受了请求，不代表设备已完成操作。

以命令状态为准：SUCCESS 表示收到设备确认；TIMEOUT 表示等待时间内没有收到最终确认。需要恢复先前命令状态时，使用查询命令结果。

返回 TIMEOUT，设备一定没有执行吗？

不一定。设备可能没有收到命令，也可能已经执行，但确认消息延迟或丢失。

不要立即盲目重复命令。先读取设备当前状态，再决定是否重试。对不可安全重复的操作尤其如此。

返回 COMMAND_REJECTED

优先检查两件事：

1. 设备类型定义是否包含该操作。
2. 参数是否符合设备能力，例如继电器序号是否越界。

如果能力和参数都正确，再检查设备在线状态与底层链路。

网络失败后应该使用新的 Idempotency-Key 吗？

如果是在重试同一次业务操作，应复用原 key。不同设备、不同目标状态或不同业务动作必须使用不同 key。

不要在所有请求中长期使用一个固定 key。完整规则参见HTTP 行为。

实时连接不稳定

WebSocket 无法建立连接

确认 access token 有效，然后创建新的 wsTicket。ticket 是短期、单用途凭证，不应缓存或复用。

依次核对创建 WebSocket Ticket和建立连接。

WebSocket 断线后应该怎么恢复？

使用退避策略重连，并为每次新连接创建新的 ticket。连接恢复后重新查询必要状态，不要假设断线期间的事件能够完整补发。

参见心跳与重连。

收到重复事件，或者感觉漏了事件

事件处理需要幂等。WebSocket 用于通知变化，不应作为唯一的永久状态来源。

页面重新加载、连接恢复或发现状态缺口时，通过 REST API 或 WebSocket 状态请求重新建立设备状态基线。

请求过多或服务暂不可用

返回 HTTP 429

停止立即重试，读取 Retry-After，到指定时间后再尝试。多个服务实例应共享退避策略，避免同时再次发起请求。

实时刷新和设备控制比快照查询限制更严格。参见限流与重试。

返回 503 或 GATEWAY_UNAVAILABLE

实时设备链路暂时不可用。记录 requestId，使用次数有限的退避重试。

如果持续发生，不要无限重试；准备排障信息后联系支持。

准备排障信息

如果以上步骤仍无法解决，请准备：

信息	示例或说明
requestId	API 响应中的请求追踪 ID
API Client ID	不要提供 clientSecret
请求方法与路径	GET /wlte/v1/devices
UTC 时间	问题发生的准确时间
HTTP 状态与业务 code	例如 403 / AUTH_SCOPE_DENIED
脱敏后的参数	移除密码、token 和个人信息

然后通过联系支持提交问题。