错误与重试
各状态的含义及应对方法。
错误以包含 detail 字段的 JSON 返回。请依据状态码和重试标头处理;保留 detail 供日志和用户提示使用。
| 状态 | 含义 | 应对方法 |
|---|---|---|
400 | 输入无效、引擎未知或路由错误 | 修正请求或选择可用引擎 |
401 | PIN 或 API 密钥缺失或错误 | 发送凭据 |
403 | 调用方不能使用本地或管理员路由 | 使用回环地址或允许的路由 |
409 | 缺少必需的模型或状态 | 安装推荐模型或解决冲突 |
422 | 请求体验证失败 | 修正字段名称、类型或范围 |
429 | GPU 队列已满 | 等待 Retry-After 后重试 |
500 | 引擎或服务器意外故障 | 记录 detail;仅在安全时重试 |
503 | 引擎加载或生成暂时不可用 | 遵守 Retry-After |
504 | 受保护的转录或生成超时 | 重试一次;若再次发生则缩短任务 |
重试
对 429、可重试的 503 和 504 使用有上限的指数退避重试。VoiceStudio 可能发送:
Retry-After: 30
X-OmniVoice-Retryable: true不要自动重试 400、401、403 或 422。409 需要先安装模型或进行其他明确修改。
配音和批处理任务在连接中断后,应从任务状态恢复,而不是重新上传媒体。