Backend Error Handling
错误分类
| 错误类型 | 检测条件 | SSE 事件 | 用户提示 |
|---|---|---|---|
| 认证错误 | 身份验证失败 | error (Unauthorized) | 重定向到登录 |
| 速率限制 | Rate limit exceeded | error (RateLimited) | 提示稍后重试 |
| 输入长度超限 | Range of input length / InvalidParameter | error | 建议缩短输入 |
| 上下文窗口溢出 | context length / token limit | error | 建议开启新会话 |
| 通用异常 | 其他所有 Exception | error | 包含 traceback 详情 |
error 事件类型返回给前端，包含 error_code 和 details 字段。
Frontend Error Handling
HTTP 状态码处理
| HTTP 状态码 | 含义 | 处理方式 |
|---|---|---|
| 401 | 未授权 | 重定向到登录页 |
| 403 | 信用额度不足 | Toast 提示充值 |
| 503 | 后端未启动 | 连接错误提示 |
| 504 | 请求超时 | 超时提示 |
流错误处理
| 错误类型 | 触发条件 | 处理方式 |
|---|---|---|
| AbortError | 用户主动取消 | 静默处理，不显示错误 |
| 网络断开 | 连接中断 | 提示网络错误 |
| 解析错误 | SSE 数据格式异常 | 记录日志，尝试恢复 |
Retry Strategy
自动重试
当遇到可恢复错误时，系统使用指数退避策略自动重试：| 配置 | 值 |
|---|---|
| 最大重试次数 | 3 次 |
| 初始等待 | 1s |
| 退避倍数 | 2x |
| 最大等待 | 8s |
不重试的错误
以下错误类型不会触发自动重试：- 认证错误（401）— 需要用户重新登录
- 信用额度不足（403）— 需要用户充值
- 用户主动取消（AbortError）— 用户意图明确
Fallback & Degradation
Event Persistence 降级
RealtimeEventSaver 在持久化失败时的降级策略：
| 阶段 | 行为 |
|---|---|
| 正常 | 批量写入 PostgreSQL（3 个事件/批，100ms 间隔） |
| 重试 | 指数退避重试，最多 3 次 |
| 降级 | 写入 LocalStorage 备份 |
| 恢复 | 下次加载时从 LocalStorage 回写服务器 |
Timeout 保护
| 超时项 | 默认值 | 说明 |
|---|---|---|
| Agent 最大执行时长 | 7200s (2h) | FastAPI 单次调用上限 |
| MCP 服务器 | 1800s (30min) | 每个 MCP 服务器的连接超时 |
| HITL 工具审批 | 可配置 | 每个工具独立设置 |
| LangGraph 递归限制 | 999 | Agent 循环的最大迭代次数 |