# 错误码

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

```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. **友好的用户提示** - 将技术错误转换为用户可理解的提示