排障：收不到推送、重复、延迟

按症状对照下列条目；配置与验签细节见 配置平台消息推送。文档未公开的阈值（如停推次数、重试间隔）以平台实际行为为准，业务侧应保证 200 响应与幂等。

收不到推送

平台主动推送（推送模式） 写明：

• 回调服务收到消息后务必返回 200。
• 若回调长期无有效 HTTP 200，平台会停止推送；修复服务后在控制台或 setMessageCallback 重新开启订阅。

getMessageCallback：查看报警回调地址 写明：未订阅时 callbackUrl、callbackFlag 为空。

setMessageCallback：设置报警回调地址 写明：接收设备消息的地址需要可以被外网访问；status 为 on 时回调地址和回调类型必填。

验签失败：按 签名 核对 system.sign；仍失败时检查 appSecret 与原始 body。超时与重试策略见 配置平台消息推送。

拉取不到消息

消息通道订阅（拉取模式） 的常见问题写明：

• 确认通道已开通且生效。
• 确认该时段有新消息。
• hasMore=false 且 count=0 表示已追上最新。

同页开通说明另写：权限开通后，新产生的消息会进入消息通道。

同页错误码：

• MC1001：通道未开通。联系商务开通消息通道并等待生效。
• OP1026：请求过于频繁。同一个 appId、同一个 group 并发调用会报此码，请避免多实例并发。
• MC1002：消费组非法。仅支持 group1 / group2 / group3。

申请方式见 订阅消息通道。

重复

平台主动推送：对 msgId 或告警唯一 id 做幂等；重试可能导致重复投递。

消息通道的常见问题写明：

• 手动模式未 commit，或自动模式处理过慢，会导致重复拉取。
• 用 msgId 做幂等。
• 生产环境请用 autoCommit=false，并在处理成功后 commitOffset。

同页还写：autoCommit=true 时位点在 pull 成功后即提交，与业务是否处理完成无关，处理失败可能丢消息。autoCommit=false 时，处理失败不要调用 commitOffset()，否则可能丢失未处理完的消息。无 pending 位点调用 commitOffset 返回 MC1003，处理建议是先 pull 产生 pending，处理后再 commit。

延迟

事件消息对接 的对比表写明：

• 平台主动推送的实时性高，近乎实时。平台一旦产生消息，会立即主动发送给开发者。
• 消息通道订阅的实时性较低，存在延迟。消息临时存储在通道中，等待下次拉取。拉取间隔直接影响实时性，文档建议间隔需在 30 秒以内。

消息通道订阅（拉取模式） 写明：hasMore=true 时，间隔不少于 1 秒继续拉取。Java SDK 的 intervalMs 默认 1000，且不少于 1000。

推送延迟：先确认回调返回 200 且处理耗时短；排查网络与下游队列。若需更低延迟，对比 拉取模式 的轮询间隔（建议小于 30 秒）。

超过保留期

offsetReset=true 表示消息超过 2 天通道保留期被清理、位点已重置（部分历史消息丢失）。这与推送延迟不同；拉取模式遇此应接受重置后继续消费。