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

{
  "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 | Next: UI Components