> ## 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.

# Retry Policy

> Zeus error handling and retry strategies

Zeus provides error capturing and retry mechanisms at every stage of message processing, ensuring the reliability of streaming and continuity of the user experience.

***

## Backend Error Handling

### Error Classification

| Error Type              | Detection Condition                      | SSE Event              | User Prompt                    |
| ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------ |
| Authentication error    | Authentication failure                   | `error` (Unauthorized) | Redirect to login              |
| Rate limiting           | Rate limit exceeded                      | `error` (RateLimited)  | Prompt to retry later          |
| Input length exceeded   | Range of input length / InvalidParameter | `error`                | Suggest shortening input       |
| Context window overflow | context length / token limit             | `error`                | Suggest starting a new session |
| General exception       | All other Exceptions                     | `error`                | Includes traceback details     |

All errors are returned to the frontend via the SSE `error` event type, containing `error_code` and `details` fields.

***

## Frontend Error Handling

### HTTP Status Code Handling

| HTTP Status Code | Meaning              | Handling                |
| ---------------- | -------------------- | ----------------------- |
| 401              | Unauthorized         | Redirect to login page  |
| 403              | Insufficient credits | Toast prompt to top up  |
| 503              | Backend not started  | Connection error prompt |
| 504              | Request timeout      | Timeout prompt          |

### Stream Error Handling

| Error Type            | Trigger Condition      | Handling                             |
| --------------------- | ---------------------- | ------------------------------------ |
| AbortError            | User manually cancels  | Silently handled, no error displayed |
| Network disconnection | Connection interrupted | Network error prompt                 |
| Parse error           | Malformed SSE data     | Log the error, attempt recovery      |

***

## Retry Strategy

### Automatic Retry

When a recoverable error is encountered, the system automatically retries using an **exponential backoff** strategy:

| Configuration      | Value |
| ------------------ | ----- |
| Max retry attempts | 3     |
| Initial wait       | 1s    |
| Backoff multiplier | 2x    |
| Max wait           | 8s    |

### Non-Retryable Errors

The following error types do not trigger automatic retries:

* Authentication error (401) — Requires user to re-login
* Insufficient credits (403) — Requires user to top up
* User-initiated cancel (AbortError) — User intent is clear

***

## Fallback & Degradation

### Event Persistence Fallback

`RealtimeEventSaver` fallback strategy when persistence fails:

| Phase    | Behavior                                                   |
| -------- | ---------------------------------------------------------- |
| Normal   | Batch write to PostgreSQL (3 events/batch, 100ms interval) |
| Retry    | Exponential backoff retry, up to 3 attempts                |
| Fallback | Write to LocalStorage as backup                            |
| Recovery | On next load, replay from LocalStorage back to server      |

### Timeout Protection

| Timeout                   | Default Value | Description                                |
| ------------------------- | ------------- | ------------------------------------------ |
| Agent max execution time  | 7200s (2h)    | Maximum duration for a single FastAPI call |
| MCP server                | 1800s (30min) | Connection timeout per MCP server          |
| HITL tool approval        | Configurable  | Independently set per tool                 |
| LangGraph recursion limit | 999           | Maximum iteration count for the Agent loop |