# 错误码与排查

## 公共错误

| 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` | 登录票据 | 观看域名或其映射暂不可用，联系部署方 |

## 排查顺序

1. 看 HTTP 状态和 `error.code`，保留 `requestId`。
2. 400 先看请求体与字段表；401 使用 [固定签名向量](./signature.md#固定校验向量) 验证算法。
3. 浏览器显示网络失败时，检查 API 地址、证书、CORS 预检与文档 CSP。浏览器未读取到响应不等于服务端未处理请求。
4. 修改参数或重试时，重新生成 timestamp、nonce 和签名。

不要上传 Secret、一次性票据、完整手机号或带票据的链接作为排查附件。只提交脱敏请求、HTTP 状态、error.code 和 requestId。