89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# 错误码
|
|
|
|
本文档列出 AI Video Assistant API 的所有错误码及其说明。
|
|
|
|
## 协议错误
|
|
|
|
| 错误码 | 说明 | 解决方案 |
|
|
|---|---|---|
|
|
| `protocol.invalid_json` | JSON 格式错误 | 检查发送的 JSON 是否合法 |
|
|
| `protocol.invalid_message` | 消息格式错误 | 检查消息结构是否符合协议 |
|
|
| `protocol.order` | 消息顺序错误 | 确保先发送 `session.start` |
|
|
| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 | 在连接 URL 中添加 `assistant_id` 参数 |
|
|
| `protocol.invalid_override` | metadata 覆盖字段不合法 | 检查 overrides 字段是否在白名单内 |
|
|
|
|
## 助手错误
|
|
|
|
| 错误码 | 说明 | 解决方案 |
|
|
|---|---|---|
|
|
| `assistant.not_found` | 助手不存在 | 检查 `assistant_id` 是否正确 |
|
|
| `assistant.config_unavailable` | 助手配置不可用 | 确认助手已正确配置并发布 |
|
|
|
|
## 音频错误
|
|
|
|
| 错误码 | 说明 | 解决方案 |
|
|
|---|---|---|
|
|
| `audio.invalid_pcm` | PCM 数据无效 | 检查音频格式是否为 `pcm_s16le` |
|
|
| `audio.frame_size_mismatch` | 音频帧大小不匹配 | 确保帧长度是 640 字节的整数倍 |
|
|
|
|
## 服务器错误
|
|
|
|
| 错误码 | 说明 | 解决方案 |
|
|
|---|---|---|
|
|
| `server.internal` | 服务端内部错误 | 查看服务端日志排查问题 |
|
|
|
|
## 错误响应格式
|
|
|
|
所有错误都通过 `error` 事件返回：
|
|
|
|
```json
|
|
{
|
|
"type": "error",
|
|
"timestamp": 1730000000000,
|
|
"sessionId": "sess_xxx",
|
|
"data": {
|
|
"code": "protocol.invalid_json",
|
|
"message": "Invalid JSON format",
|
|
"details": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
## HTTP API 错误
|
|
|
|
REST API 使用标准 HTTP 状态码：
|
|
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 200 | 请求成功 |
|
|
| 201 | 创建成功 |
|
|
| 400 | 请求参数错误 |
|
|
| 401 | 未授权（缺少或无效的认证信息） |
|
|
| 403 | 禁止访问（权限不足） |
|
|
| 404 | 资源不存在 |
|
|
| 422 | 请求实体无法处理 |
|
|
| 500 | 服务器内部错误 |
|
|
|
|
### HTTP 错误响应示例
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Invalid request parameters",
|
|
"details": {
|
|
"field": "name",
|
|
"reason": "required"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 错误处理最佳实践
|
|
|
|
1. **始终检查错误响应** - 不要假设请求一定成功
|
|
2. **实现重试机制** - 对于临时性错误（如网络问题）实现指数退避重试
|
|
3. **记录错误日志** - 保存错误详情用于问题排查
|
|
4. **友好的用户提示** - 将技术错误转换为用户可理解的提示
|