错误诊断

按 HTTP 状态、业务错误码和请求 ID 定位问题。先读取失败响应，再按对应步骤检查配置或查询安全诊断。

留下可定位的信息

以响应头 X-Request-ID 作为关联标识。平台格式错误体中的 error.request_id 与它相同；微信兼容接口使用顶层 errcode、errmsg，不保证存在 error.request_id 或 rid。网关可能替换客户端自带的值，以实际响应为准。

应用后端可以使用当前接口 token 查询本应用最近 7 天的单条失败诊断：

POST /miniapp/v1/apps/{app_id}/diagnostics/request
Authorization: Bearer <interface-token>
Content-Type: application/json

{"request_id":"响应中的关联标识"}

响应只包含时间、耗时、路由模板、HTTP 状态、业务错误码和安全的阶段、规则、字段名、失败分类及依赖结果。严格 JSON 解码失败时，可选的 field 用于指出未知字段或类型错误涉及的字段路径；它不包含字段值。平台不保存或返回完整 URL 查询、请求正文、响应正文、Authorization、Cookie、AppSecret、token、code、手机号、用户资料或客户端 IP。跨应用、不存在和超过 7 天的记录都返回 404。

应用后端也可使用以下命令；REQUEST_ID 取自失败响应的 X-Request-ID，ACCESS_TOKEN 是同一应用的当前接口 token：

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/diagnostics/request" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"request_id\":\"$REQUEST_ID\"}"

请求 ID 只接受字母、数字、下划线、点和短横线，最长 128 字符；本例按响应的合法值填写。成功为 HTTP 200、code=miniapp_success，安全摘要位于 data。完整字段见失败诊断 API。查询 404 不证明原操作成功或失败；原请求未确认应用身份、记录过期或归属不同应用时都可能无可查记录。

有权管理员也可在应用详情进入“诊断与审计”查询。需要人工协助时，反馈应用 ID、版本、操作时间、调用接口、HTTP 状态、响应错误码和实际响应中的关联标识；不要提交凭据、一次性 code、短信验证码或完整用户资料。

用户反馈与投诉

平台反馈用于功能异常、支付问题和产品建议，由当前应用有运营权限的人员跟进；违规投诉由平台受理，应用成员不会因拥有开发或版本审核权限而取得投诉证据。支付问题被受理不代表退款或处罚已经完成，仍需按对应业务流程办理。

有当前应用运营权限的成员，在“开发者中心 → 我的应用 → 选择小程序 → 用户反馈”查看和处理反馈。详情支持指派处理人、回复、答复结案、关闭与重开，并保留沟通和办理历史。违规投诉由平台管理员在独立“投诉管理”办理，不在应用反馈列表展示。

从40.13.0起，宿主GET工单详情的ticket.attachments及messages[].attachments直接提供图片信息：available/approved含60秒地址，其他状态无地址；到期刷新详情或使用独立附件查询。上传响应中的attachment_id只表示材料上传成功，不能据此认定图片已经审核通过。

图片上传行为需按运行版本判断。40.12.0起支持可选内容审核，默认关闭时新图片显示“可查看（未审核）”；开启审核时仍等待阿里云审核。升级前40.11.0上传的图片处于“安全检查中”，保持原状态，通过后才能查看。详见版本说明。

上传成功返回附件元数据和状态，不直接返回图片地址；打开图片时需另行查询。上传响应和查询响应使用独立文档模型，查询中的可选图片地址不代表上传会返回该字段。审核异常或未通过时保持不可查看。升级或切换开关不会自动放行已有待审或拒绝图片。未绑定图片的24小时临时保留期限与查看地址的60秒有效期不同，查看地址到期后需重新获取。

若办理结果暂不能确认，先刷新核对；需要重试时使用页面保留的原操作，不要修改内容重复提交。工单被他人更新时，页面刷新最新详情，由处理人核对后重新确认。

这组能力属于宿主和管理工作区内部协议，小程序 JS 与应用业务后端无需补充调用，也不要求用户先完成小程序业务登录。本次仅接入Web工作区，Android/iOS宿主入口另行交付；审核开关、阿里云账号及规则由平台运维设置，应用开发者无需提供密钥。开启审核模式的真实云接入需单独验收。实际入口开放以对应客户端和工作区发布记录为准。

需要定位问题时，保留前文列出的 AppID、版本、时间和响应关联标识；只提交必要说明及脱敏截图。微信公开反馈列表及图片查询兼容接口不属于本版开放范围。

按失败阶段排查

下表用于平台原生接口。微信兼容登录、token 和手机号另按后文的 HTTP 200 与 errcode 规则判断。

现象	检查顺序
401	登录兑换/获取接口 token 时检查 AppSecret、应用状态、代次和冻结状态；其他后端接口检查接口 token 的应用、到期和吊销状态；会话接口再检查平台会话及其有效期
403	当前身份权限、体验资格、制品能力声明、当前环境的能力审核、当前隐私指引同意及 scope；系统权限另查宿主设置
404	应用/版本是否可见、code 是否有效；确认没有调用已删除的固定登录转发路由
409	版本/revision、授权设置或订单状态冲突；支付余额、钱包及商户账户拒绝按具体错误码处理，先查订单状态后由操作者确认
429	按 Retry-After 等待并限制重试频率
503 / 504	依赖配置、服务不可用或结果未明；提交请求 ID，支付和退款先按原业务号查单，不自动重放一次性操作

平台错误码以API 参考的响应定义为准；retryable: false 表示客户端不得自动重试。MetaEco 余额支付的 401 先检查接口 token、有效公钥和四个签名头；409 按具体错误码区分 nonce 重放、订单冲突、余额或商户账户问题，不能统一换号重试。

微信兼容接口可能以 HTTP 200 返回非零 errcode，不能仅按 HTTP 状态判断成功。已完成应用身份认证的这类失败可查询应用诊断；身份未确认的请求不会归入某个应用。HTTP 状态与业务错误码应一起使用，具体响应以对应 API 参考为准。接口 token 无效时可用当前 AppSecret 重新获取一次；参数错误修正请求后再试，过期或已消费的 code 必须重新取得。

发布与包加载

分发成功只说明取得了候选包，宿主还必须完成摘要、签名和包格式验证。校验失败不能关闭验签绕过。记录宿主版本、SDK 版本和制品摘要，区分下载失败、验签失败与实际运行失败。

客户端实时日志

当前不提供 wx.getRealtimeLogManager、手机端日志上报或 We分析式查询。服务端 request_id 诊断只用于定位平台接口失败，不能代替小程序页面运行日志。

隐私指引主体名称

已补充并通过主体核验后，重新打开「填写用户隐私保护指引」，名称应自动带入并只读显示。miniapp_privacy_subject_mismatch 表示提交名称与当前核验主体不符，请关闭并重新打开编辑器、核对全文后预览。模板查询失败或返回 503 时，不要用应用展示名称代替，刷新重试并保留请求 ID。主体核验和隐私指引审核分别生效；旧指引中的名称是历史快照。

预期结果与下一步

诊断结果明确失败阶段与处理方式。修正配置后重新执行原业务步骤；支付结果未明时先查原单。需要协助时只提交本页列出的定位信息。