常见问题
排查设备上线、App 来电、信令协商和媒体连接问题。
故障排查
设备已经绑定到租户,为什么提示 LICENSE_REQUIRED?
检查设备本机 License 是否有效,以及 MQTT 配置是否传入 .withDeviceLicense(license)。按设备激活与续费指南完成生码、联网激活和授权初始化,设备 UUID 须与授权 SN 一致。
设备重启后为什么需要联网校时?
SDK 用平台时间和单调时钟校验授权。设备重启或无法确认开机标识时返回 CLOCK_UNTRUSTED,调用 refreshAsync 恢复授权和时间。同一开机内进程重启可以继续使用保存的可信时间锚点。
激活请求重试会重复增加年限吗?
每笔购买只增加一次期限,使用原凭证和 SN 重试会取回该笔购买的原 License。续费需要后台生成绑定原 SN 的新购买记录,操作见续费与重试步骤。
设备已连上 Broker,为什么平台仍显示离线?
先确认设备绑定到正确的租户,并核对双方使用的 Broker。设备需订阅下行 Topic,并收到平台对 connect 和 intercomResume 的业务应答。检查 Topic 权限及通话日志里的回复,Broker 的 PUBACK 仅确认 MQTT 传输。
设备按铃后,App 为什么没有收到来电?
检查租户回调是否成功送达、业务系统是否发出通知,以及接听后是否指定了正确的用户并将 callId 交给 SDK。在后台查看业务通知投递状态。
HTTP 返回 401,或者 WebSocket 无法握手?
核对业务网关的登录凭据、租户和用户。签名端与平台需要使用同一 AppKey、原始请求路径和查询串,并保持时钟同步。WebSocket 还需检查反向代理是否转发升级头。
能听到声音,为什么没有视频,或者跨网无法接通?
确认使用 videoAudio,发送端已授权摄像头且开启本地视频,接收端已绑定远端渲染器。跨网失败时检查 TURN 地址、凭据和端口连通性,接通后可在通话列表核对媒体路径。
响铃或接通后自动结束,该看什么?
先看「结束原因」。deviceAckTimeout 表示平台等待设备业务应答超时,phaseTimeout 表示通话阶段超时,mediaLivenessTimeout 表示媒体保活超时。按通话 ID 查最近一条信令或状态报文。
协议错误码与 SDK 提示
对讲 HTTP 接口用响应体 code=1 表示成功,失败时 data 给出协议错误标识。MQTT 业务应答用 000000 表示成功。
| HTTP / SDK 标识 | MQTT | 含义与排查方向 |
|---|---|---|
INTERCOM_CALL_ID_INVALID | 210000 | 通话 ID 缺失或格式无效。检查业务系统传入的 callId。 |
INTERCOM_CALL_NOT_FOUND | 210001 | 通话不存在或当前用户不可访问。核对租户、用户及设备。 |
INTERCOM_INVALID_STATE | 210002 | 当前阶段不允许该操作。先查询权威通话状态。 |
INTERCOM_UNAUTHORIZED / INTERCOM_DEVICE_FORBIDDEN | 210003 | 访问被拒绝。核对业务身份、设备绑定及 Topic 权限。 |
INTERCOM_DEVICE_OFFLINE | 210004 | 设备未就绪。检查 Broker 连接及设备恢复对账。 |
INTERCOM_DEVICE_BUSY | 210005 | 设备或用户已有活动通话。确认旧通话已结束。 |
INTERCOM_IDEMPOTENCY_CONFLICT | 210006 | 重试编号相同但内容不同。原请求重试时保持原编号和正文。 |
INTERCOM_INVALID_REQUEST / INTERCOM_SIGNAL_GAP / INTERCOM_SIGNAL_TOO_LARGE | 210007 | 参数、信令大小或序号异常。检查字段、大小和连续序号。 |
INTERCOM_MEDIA_UNSUPPORTED | 210008 | 媒体能力不匹配。检查音视频类型、编码和 SDP。 |
INTERCOM_CALL_EXPIRED | 210009 | 通话已过期限。核对通话状态与设备时钟。 |
| — | 210010 | 设备拒接平台下发的呼叫。 |
INTERCOM_INTERNAL_ERROR / INTERCOM_TURN_UNAVAILABLE | 310000 | 平台内部异常或网络穿透配置未就绪。检查服务日志、数据库、租户回调与 TURN 配置。 |
MQTT_RESULT_UNKNOWN | — | SDK 在重试窗口内未收到匹配的业务应答。按流水号核对上行、平台处理和回复 Topic。 |