错误与故障切换

Hub 自身的错误

状态码	响应	原因
401	{"detail": {"error": "Missing API key"}}	没有提供 Hub Key
401	{"detail": {"error": "Invalid API key"}}	Key 不存在或已停用
400	{"detail": {"error": "Body must be JSON"}}	POST /v2/transcript 请求体不是 JSON
404	{"detail": {"error": "Transcript not found"}}	该转写不是经 Hub 创建的
503	{"error": "hub: No upstream account available"}	没有可用账号（全部停用、异常、冷却或并发已满，或指定区域没有账号）
503	{"error": "hub: All upstream accounts failed"}	尝试的账号都因网络错误失败

上游错误

其它错误都是 AssemblyAI 的原始响应（状态码、响应体都不变），例如参数错误的 400。

当所有尝试的账号都返回可重试的错误（429、401、402、403、5xx）时，Hub 返回最后一个账号的原始响应。

故障切换规则

情况	账号状态变化	是否换号重试
429 限流	冷却 COOLDOWN_SECONDS 秒后自动恢复	是
401 / 402 / 403	标为「异常」，需在控制台重置或修正 Key	是
500 / 502 / 503 / 504	不变	是
网络错误	不变	是
其它状态码	不变	否，直接返回

• 单次请求最多尝试 MAX_RETRY_ACCOUNTS 个不同账号。
• 请求体会先缓存（32 MB 以内在内存，更大写临时文件），换号时完整重放。
• 绑定到特定账号的请求不换号：查询、删除、导出已有转写，用 Hub 上传的文件提交转写，带 transcript_id 的语音理解。这些资源只存在于原账号，换号也无法访问。原账号返回 401/403/429 时同样会更新它的状态。
• 实时中继在建立连接时选号，会话中途不换号。

排查建议

1. 控制台「上游账号」查看各账号状态和最近错误，点「测试」验证 Key。
2. 「任务」页查看失败任务的错误信息。
3. docker compose logs -f app 查看 Hub 日志，换号时会记录 account N got <状态码>。