d0897aca92
- Changed site name and description in mkdocs.yml. - Revised content in index.md to provide a comprehensive overview of RAS features and capabilities. - Updated API reference and error documentation to replace AI Video Assistant with RAS. - Modified deployment and getting started guides to align with the new branding. - Enhanced quickstart instructions to specify RAS service requirements.
2.5 KiB
2.5 KiB
错误码
本文档列出 Realtime Agent Studio (RAS) 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"
}
}
}
错误处理最佳实践
- 始终检查错误响应 - 不要假设请求一定成功
- 实现重试机制 - 对于临时性错误（如网络问题）实现指数退避重试
- 记录错误日志 - 保存错误详情用于问题排查
- 友好的用户提示 - 将技术错误转换为用户可理解的提示