AI-VideoAssistant/docs/content/api-reference/errors.md

错误码

本文档列出 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 事件返回：

{
  "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 错误响应示例

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

错误处理最佳实践

1. 始终检查错误响应 - 不要假设请求一定成功
2. 实现重试机制 - 对于临时性错误（如网络问题）实现指数退避重试
3. 记录错误日志 - 保存错误详情用于问题排查
4. 友好的用户提示 - 将技术错误转换为用户可理解的提示