immish/docs/error-handling.md

# Error Handling

The app implements comprehensive error handling to provide a robust user experience.

## Error Architecture

```
┌─────────────────────────────────────────┐
│              UI Layer                   │
│  (Shows error messages to user)         │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│          State Management               │
│  (Catches errors, updates state)        │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│            Service Layer                │
│  (Logs errors, returns defaults)        │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│          Repository Layer               │
│  (Handles API/DB errors)                │
└─────────────────────────────────────────┘
```

## Error Logger Mixin

Services use a standardized error handling pattern:

### Guard Error

Wraps async operations and returns result or error:

```
Input: Async function
Output: AsyncValue<T>
  - AsyncData(result) on success
  - AsyncError(error, stackTrace) on failure

Behavior:
1. Execute async function
2. If success → return AsyncData with result
3. If exception → log error, return AsyncError
```

### Log Error

Executes operation and returns default on failure:

```
Input:
  - Async function
  - Default value
  - Error message

Output: T (result or default)

Behavior:
1. Execute async function
2. If success → return result
3. If exception → log error, return default value
```

## Log Levels

| Level | Value | Usage |
|-------|-------|-------|
| ALL | 0 | All messages |
| FINEST | 300 | Extremely detailed |
| FINER | 400 | Very detailed |
| FINE | 500 | Detailed tracing |
| CONFIG | 700 | Configuration info |
| INFO | 800 | General information |
| WARNING | 900 | Potential problems |
| SEVERE | 1000 | Serious failures |
| SHOUT | 1200 | Critical errors |
| OFF | 2000 | No logging |

Default level: INFO (800)

## API Error Handling

### HTTP Error Responses

| Status Code | Meaning | Handling |
|-------------|---------|----------|
| 400 | Bad Request | Show validation error |
| 401 | Unauthorized | Redirect to login |
| 403 | Forbidden | Show access denied |
| 404 | Not Found | Show not found message |
| 409 | Conflict | Handle duplicate |
| 500 | Server Error | Show generic error |

### Network Errors

| Error Type | Handling |
|------------|----------|
| No Connection | Show offline message |
| Timeout | Retry with backoff |
| SSL Error | Check certificate settings |
| DNS Failure | Check server URL |

### Error Response Format

```json
{
  "error": "ErrorType",
  "statusCode": 400,
  "message": "Human-readable error message"
}
```

## Authentication Errors

### Login Failures

| Error | Message | Action |
|-------|---------|--------|
| Wrong credentials | "Incorrect email or password" | Show error, stay on login |
| Account locked | "Account temporarily locked" | Show lockout message |
| Server unavailable | "Cannot connect to server" | Check server URL |

### Session Expiration

1. API returns 401
2. Clear local token
3. Navigate to login
4. Show "Session expired" message

### OAuth Errors

| Error | Handling |
|-------|----------|
| User cancelled | Return to login silently |
| Invalid state | Show security error |
| Token exchange failed | Show error, retry option |

## Upload Errors

### Upload Failure Handling

```
Upload Attempt
      │
      ▼
   Success?
   │      │
  Yes     No
   │      │
   ▼      ▼
 Done   Retry?
        │    │
       Yes   No (max retries)
        │    │
        ▼    ▼
     Retry  Mark Failed
              │
              ▼
         Add to Error Queue
              │
              ▼
         Grace Period Check
              │
         ┌────┴────┐
         │         │
      Within    Exceeded
         │         │
         ▼         ▼
      Silent   Show Notification
```

### Error Grace Period

- Don't immediately notify on upload failures
- Wait for `uploadErrorNotificationGracePeriod` failures
- Then show notification
- Prevents spam for transient errors

### Duplicate Detection

When server returns duplicate error:
1. Mark local asset as backed up
2. Don't show error to user
3. Continue with next asset

## Download Errors

| Error | Handling |
|-------|----------|
| Asset not found | Show "Photo not available" |
| Permission denied | Show access error |
| Storage full | Show storage warning |
| Network error | Offer retry |

## Sync Errors

### Sync Failure Recovery

1. Log sync error
2. Keep existing local data
3. Schedule retry
4. Show sync indicator if prolonged

### Conflict Resolution

When local and remote conflict:
1. Remote data takes precedence
2. Merge where possible
3. Log conflict details

## UI Error Display

### Snackbar Messages

For transient errors:
```
┌────────────────────────────────────┐
│  Error message here         [RETRY]│
└────────────────────────────────────┘
```

- Auto-dismiss after 3-5 seconds
- Optional action button
- Non-blocking

### Dialog Messages

For critical errors requiring action:
```
┌─────────────────────────────────┐
│          Error Title            │
├─────────────────────────────────┤
│                                 │
│  Detailed error description     │
│  with helpful guidance.         │
│                                 │
├─────────────────────────────────┤
│           [OK]  [RETRY]         │
└─────────────────────────────────┘
```

### Inline Errors

For form validation:
```
┌─────────────────────────────────┐
│  Email                          │
│  ┌───────────────────────────┐  │
│  │ invalid-email             │  │
│  └───────────────────────────┘  │
│  ⚠ Please enter a valid email   │
└─────────────────────────────────┘
```

### Empty States

When no data due to error:
```
┌─────────────────────────────────┐
│                                 │
│         [Error Icon]            │
│                                 │
│    Something went wrong         │
│                                 │
│         [Try Again]             │
│                                 │
└─────────────────────────────────┘
```

## Localization Keys

Common error message keys:

| Key | Usage |
|-----|-------|
| `error_generic` | Unknown error occurred |
| `error_network` | Network connection error |
| `error_server` | Server error |
| `error_unauthorized` | Not authorized |
| `error_not_found` | Resource not found |
| `error_upload_failed` | Upload failed |
| `error_download_failed` | Download failed |

## Debug Logging

### Enable Advanced Troubleshooting

When enabled in settings:
- Log all API requests/responses
- Log state changes
- Log error stack traces
- Log sync operations

### Log Output

Logs include:
- Timestamp
- Logger name (component)
- Log level
- Message
- Error object (if applicable)
- Stack trace (if applicable)

### Viewing Logs

- Settings → Advanced → Export Logs
- Share log file for support

## Error Recovery Patterns

### Automatic Retry

For transient failures:
```
Attempt 1
   ↓
 Fail → Wait 1s → Attempt 2
                     ↓
                  Fail → Wait 2s → Attempt 3
                                      ↓
                                   Fail → Give Up
```

### Manual Retry

User-triggered retry:
1. Show error with retry button
2. User taps retry
3. Clear error state
4. Repeat operation

### Graceful Degradation

When feature unavailable:
1. Disable affected UI elements
2. Show explanation
3. Continue with available features

---

[Previous: Settings](settings.md) | [Next: UI Components](ui-components.md)