错误码

错误形状

所有错误统一返回：

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "API Key 无效，请检查配置"
  }
}

code	HTTP	含义与处理
`API_KEY_INVALID`	401	Key 无效、已撤销或格式不对。检查 Key 配置；确认带了 `Authorization: Bearer` 头
`TEAM_API_DISABLED`	4xx	团队关掉了 API 总闸。换 Key 没用，联系团队管理员在「API 密钥」页打开
`API_MODEL_NOT_ALLOWED`	403	模型不在这把 Key 的白名单里。换白名单内的模型，或找管理员放开

code	HTTP	含义与处理
`INSUFFICIENT_BALANCE`	4xx	团队点数不足，去充值

code	HTTP	含义与处理
`INVALID_REQUEST`	400	参数不合法，`message` 里有具体原因。常见：漏了 `request_id`、`params`/`refs` 不是合法 JSON、refs 里不是 http(s) 地址
`TASK_NOT_FOUND`	404	任务编号不存在或不属于你的团队
`AI_MODEL_NOT_FOUND`	4xx	模型不存在或已下架，对照左侧模型页检查 `model` 拼写
`AI_AUDIO_URL_UNREACHABLE`	400	语音识别的音频地址下载不了（过期、404、不是公网地址、下载太慢），`message` 里有具体原因
`AI_AUDIO_INVALID`	400	音频本身有问题：不是音频、带视频画面、文件损坏、超过 200 MB 或 2 小时

code	HTTP	含义与处理
`EXTRACT_URL_UNSUPPORTED`	400	链接不属于支持的平台，对照 `GET /v1/extract/sources` 检查
`EXTRACT_URL_INVALID`	400	内容取不到：链接残缺、作品已删除或设为私密
`EXTRACT_CONTENT_BLOCKED`	400	内容有版权或地区限制，换链接也没用
`EXTRACT_IN_PROGRESS`	409	同一条内容正在被本团队另一个请求解析，等几十秒再试
`EXTRACT_UPSTREAM_FAILED`	503	平台接口暂时失败，稍后重试（不扣费）

任务 status = failed 时，失败原因在任务对象的 error_code 里，点数已自动退还：

error_code	含义
`AI_UPSTREAM_FAILED`	上游生成失败。参考图拉不到也会表现为这个
`AI_CONTENT_POLICY_VIOLATION`	内容被安全策略拦截，换提示词
`AI_AUDIO_URL_UNREACHABLE`	语音识别执行时音频地址读不到了（比如签名地址在执行前过期）
`AI_AUDIO_INVALID`	语音识别时音频解不开
`INVALID_REQUEST`	语音识别执行时读到的音频比提交时量的长得多（地址背后的文件被换了），重新提交

code	HTTP	含义与处理
`INTERNAL_FAILURE`	500	服务端开小差。用同一个 `request_id` 重试（幂等，不会重复扣费）；持续出现请联系我们