Retry Policy

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

Get Started

Fundamentals

Core Capabilities

Infra

Channels

Retry Policy

Backend Error Handling

Error Classification

Frontend Error Handling

HTTP Status Code Handling

Stream Error Handling

Retry Strategy

Automatic Retry

Non-Retryable Errors

Fallback & Degradation

Event Persistence Fallback

Timeout Protection

​Backend Error Handling

​Error Classification

​Frontend Error Handling

​HTTP Status Code Handling

​Stream Error Handling

​Retry Strategy

​Automatic Retry

​Non-Retryable Errors

​Fallback & Degradation

​Event Persistence Fallback

​Timeout Protection

Backend Error Handling

Error Classification

Frontend Error Handling

HTTP Status Code Handling

Stream Error Handling

Retry Strategy

Automatic Retry

Non-Retryable Errors

Fallback & Degradation

Event Persistence Fallback

Timeout Protection