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