SDK 错误与待核对请求
网络失败时保留真实状态,避免重复消息和重复业务执行。
排查表
| 现象 | 处理 |
|---|---|
| SESSION_ALREADY_IN_USE | 同 scope 已有实例,复用或先销毁,不创建竞争客户端 |
| storageError / 本地存储不可用 | 停止发送并提示存储权限;不可丢失幂等记录后继续 |
| 401 / 会话过期 | 提示重新开始;不得换身份自动重放旧消息 |
| 403 / 入口或来源被拒绝 | 核对入口启用、公开 key、entryId 与来源限制 |
| 429 | 按错误 retryAfter 退避,保留待核对请求 |
| 网络断开但 pending 仍存在 | refresh() 读取对账;用户确认后 retryPending 使用原请求 |
| 验证码 / 真人验证要求 | 无 UI SDK 没有验证码界面,转现有完整网页处理 |
重试步骤
- 向用户显示“结果待核对”,不要直接宣布失败或成功。
- refresh() 读取会话;按消息 ID 与待核对状态确认是否已收到并处理。
- 需要重试时调用 retryPending(action),沿用原请求标识;不要另一次 sendText 重发同一请求。
- 用户明确放弃本地重试时 discardPending(action);说明这不会撤销服务端已收到的工作。
实现依据 · 仓库内路径
sdk/wechat-miniapp/index.jssdk/wechat-miniapp/index.d.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。