> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 重试策略

> Zeus 错误处理与重试策略

Zeus 在消息处理的各个环节提供错误捕获和重试机制，确保流式传输的可靠性和用户体验的连续性。

***

## 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 详情 |

所有错误均通过 SSE 的 `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 循环的最大迭代次数 |