错误码与排查
公共错误
| HTTP | error.code | 原因与处理 |
|---|---|---|
| 400 | REQUEST_INVALID | 缺失／重复签名头、非法 nonce、未知 JSON 字段、请求体超限或参数不符约束；核对参数表 |
| 401 | OPEN_API_UNAUTHORIZED | Key 不存在／被撤销、签名不匹配、时间偏差超限或 Path 非规范；使用固定向量检查算法 |
| 403 | ORIGIN_FORBIDDEN | 在线调试的文档 Origin 未获 CORS 许可；由部署方配置允许来源 |
| 403 | TENANT_SUSPENDED | 商户已停用；联系管理员 |
| 409 | OPEN_API_REPLAYED | nonce 已使用；重新生成 timestamp、nonce 和签名 |
| 503 | AUTH_DEPENDENCY_UNAVAILABLE | 鉴权、观众存储或票据依赖暂不可用；联系部署方，并为重试重新签名 |
| 500 | INTERNAL_ERROR | 未预期服务错误；提供 requestId 排查 |
网关或 HTTP 服务也可能以 413 拒绝超大请求，且不一定返回 JSON；Open API 签名中间件发现请求体超限时返回 400 REQUEST_INVALID。
接口特有错误
| HTTP | error.code | 适用接口 | 处理 |
|---|---|---|---|
| 400 | CONTENT_SENSITIVE | 创建或更新观众 | 昵称被内容审核拒绝，修改后重试；可含 details.matches |
| 503 | CONTENT_MODERATION_UNAVAILABLE | 创建或更新观众 | 启用的内容审核服务不可用，稍后重试 |
| 409 | VIEWER_IDENTITY_CONFLICT | 创建或更新观众 | 手机号被同商户其他观众占用，包括新外部标识试图关联已有手机号；改用未占用的号码，不自动合并 |
| 409 | VIEWER_UID_EXHAUSTED | 创建或更新观众 | 商户观众 UID 容量已达上限，联系部署方 |
| 404 | VIEWER_NOT_FOUND | 登录票据 | UID 不属于当前商户或不存在，先建立映射 |
| 404 | WEBINAR_NOT_FOUND | 登录票据／观看查询 | 公开码不存在或不属于当前商户；签发票据还要求活动已发布 |
| 400 | WATCH_REQUEST_INVALID | 观众明细 | 筛选合计超过 300，或游标不匹配当前查询；首次查询删除 cursor |
| 409 | WATCH_DATA_NOT_FINAL | 观众明细 | 查询含未最终落库的直播数据；等待直播最终化，或明确只查询 REPLAY |
| 503 | WATCH_DATA_UNAVAILABLE | 观看查询 | 数据存储／实时汇总暂不可用或完整性检查未通过；不是零观看数据 |
| 503 | PUBLIC_METADATA_UNAVAILABLE | 登录票据 | 活动信息暂不可用；提供 requestId 排查 |
| 503 | VIEWER_DOMAIN_UNAVAILABLE | 登录票据 | 观看域名或其映射暂不可用，联系部署方 |
排查顺序
- 看 HTTP 状态和
error.code，保留requestId。 - 400 先看请求体与字段表；401 使用 固定签名向量 验证算法。
- 浏览器显示网络失败时，检查 API 地址、证书、CORS 预检与文档 CSP。浏览器未读取到响应不等于服务端未处理请求。
- 修改参数或重试时，重新生成 timestamp、nonce 和签名。
不要上传 Secret、一次性票据、完整手机号或带票据的链接作为排查附件。只提交脱敏请求、HTTP 状态、error.code 和 requestId。