使用指南
错误码与排查
鉴权、模型、视频、素材、真人授权和限流错误处理
面向平台用户的操作步骤与创作流程说明
错误码与排查
排查时先记录 HTTP 状态、RequestId、模型 ID、任务 ID、素材 ID和原始错误码。不要记录 API Key、SecretKey 或完整真人会话 Token。
HTTP 状态
| HTTP | 含义 | 建议 |
|---|---|---|
400 | 参数或 JSON 不符合接口要求 | 对照字段表修正，不能自动重试。 |
401 | API Key、AccessKey、签名或登录态无效 | 检查凭据、时间、签名和有效期。 |
403 | 当前账户无权限 | 检查用户分组、模型授权或资源归属。 |
404 | 任务或资源不存在 | 确认 ID 与创建账户一致。 |
409 | 同一业务请求冲突 | 检查幂等身份和请求正文。 |
429 | 请求频率或额度受限 | 按响应提示等待，降低并发。 |
500 | 请求执行失败 | 读取错误码，判断是参数、素材还是服务异常。 |
503 | 模型或服务暂不可用 | 刷新模型目录、切换可用模型或稍后重试。 |
常见模型与素材错误
| 错误 | 原因 | 处理 |
|---|---|---|
model_not_found / No available channel | 当前 Key 或分组没有可用模型渠道 | 重新查询 /v1/models 并切换模型。 |
invalid_parameter | 参数组合不支持 | 核对模型、分辨率、比例、时长和参考类型。 |
ResourceDownloadFailed | 媒体 URL 无法直接下载 | 使用公开 HTTPS 文件地址，检查状态码和 Content-Type。 |
Processing | 素材仍在处理 | 保留素材 ID，稍后查询，不重复入库。 |
Failed | 素材处理失败 | 展示 Error.Code 和 Error.Message，修正后重新提交。 |
真人授权错误
| 提示 | 原因 | 处理 |
|---|---|---|
| 真人授权尚未完成 | 用户未完成手机采集 | 保留当前二维码，完成后再次解析。 |
| 真人授权会话不存在或无权访问 | Token 过期、已使用或属于其他用户 | 当前用户重新创建二维码。 |
| 该真人素材已绑定其他用户 | 同一真人分组不能跨账户复用 | 使用原绑定账户，或由本人为当前账户重新授权。 |
| 真人素材服务尚未配置 | 平台服务配置缺失 | 联系平台支持，不要在客户端改签名。 |
AccessKey 签名检查
X-Date使用 UTC 格式YYYYMMDDTHHMMSSZ。- Credential 日期与
X-Date前 8 位一致。 - Query 按键排序并正确编码。
- 签名 Header 与实际请求值完全相同。
- Payload Hash 根据最终发送字节计算。
- 派生顺序为日期、
cn-beijing、ark、request。 - SecretKey 未被截断、转义或带入首尾空格。
异步任务错误处理
创建请求已取得任务 ID后，任何本地超时都先查询原任务。只有查询返回明确终态失败时才提示用户重试。错误详情应规范化为一条可读原因，避免把多层转义 JSON 重复展示。
提交支持信息
提供发生时间、RequestId、任务 ID、模型 ID、接口路径、HTTP 状态、错误码和脱敏后的请求结构。不要提供密钥、完整用户媒体 URL、Cookie 或真人采集信息。