故障排查中心

不要用连续重试代替定位。一次通知投递至少经过调用方、网络、平台 API、平台业务校验和客户端展示五层，HTTP 2xx 只证明请求到达了某个 HTTP 入口。

快速分流

现象	首先检查	下一步
DNS、连接或 TLS 失败	域名、代理、出口网络、证书时间	从部署环境执行最小 HTTPS 请求
HTTP 401 / 403	Token、Secret、签名、IP 白名单	检查凭据所属应用及服务器时间
HTTP 404	API 路径、Bot 是否存在、资源 ID	对照当前官方文档，不重复提交
HTTP 429	平台和目标级限流	读取 Retry-After 或业务字段并退避
HTTP 2xx 但业务码失败	参数、权限、可用范围、目标 ID	记录脱敏业务码和请求 ID
接口成功但客户端没消息	目标会话、应用范围、禁言、免打扰	用一个明确可见的测试账号确认
回调重复	回调超时、确认失败、缺少事件去重	先确认，再以事件 ID 幂等处理
AI 回复错乱	同会话并发、上下文键不稳定	对同一会话串行并保留平台线程 ID

发送失败

1. 用教程中的最小纯文本请求复现，移除卡片、附件、提及和 Markdown。
2. 同时记录 HTTP 状态、平台业务码、请求 ID、目标类型和耗时，不记录完整凭据。
3. 确认凭据与目标属于同一应用、工作区、企业或 Bot。
4. 检查权限是否已经审批并随新版本发布，而不是只在控制台保存。
5. 检查目标是否在应用可用范围内，以及机器人是否已加入对应群或频道。
6. 只有限流、网络超时和平台 5xx 适合有限重试；认证和参数错误应直接进入人工排查。

收不到回调

• 确认平台配置的是当前公网 HTTPS 地址，路径和环境没有混用。
• 使用平台提供的状态接口或控制台检查最近一次失败原因。
• 验证签名时保留原始请求体；JSON 解析后再序列化会改变摘要。
• 回调入口先完成验签、落去重记录并快速响应，慢业务进入队列。
• 长连接模式检查连接状态、重连日志、订阅事件和应用版本。

消息重复或乱序

以平台稳定事件 ID 建唯一键，不使用显示名、消息文本或内存集合代替持久化去重。发送重试应使用平台幂等字段，或在业务侧保存“事件 ID -> 回复消息 ID”。同一个群、线程或私聊的对话任务需要串行化；不同会话可以并行。

提交排障信息

问题记录应包含：平台与接入方式、发生时间和时区、部署区域、HTTP 状态、脱敏业务码、请求 ID、最小复现步骤、预期与实际结果。凭据、完整 Webhook、用户隐私数据和未脱敏消息正文不得进入 Issue 或聊天记录。

仍无法定位时，回到对应教程的“能力边界”和“官方资料”，确认平台是否真的支持当前群类型、接收对象和消息方向。