⚠️ Error & Exception Handling Standards for Flutter

Table of Contents

• Core Standards
• Failure Types
• Error Handling Patterns
• Network Error Handling
• UI Error Handling
• Logging and Monitoring
• Common Violations

Core Standards

Error Handling Requirements

1. Always use structured error handling with Failure classes
2. Implement proper error mapping for different error types
3. Use safeCall wrapper for network operations
4. Handle errors gracefully in UI components
5. Log errors appropriately with context
6. Provide meaningful error messages to users
7. Implement proper error recovery mechanisms
8. Use Result pattern for error handling

Error Handling Patterns

1. Use Result pattern for operations that can fail
2. Implement proper error mapping from exceptions to failures
3. Use safeCall wrapper for network operations
4. Handle errors at appropriate levels (UI, Service, Repository)
5. Provide fallback mechanisms for critical operations
6. Use proper error propagation through the call stack

Failure Types

Failure Classification Rules

1. ServerFailure - Server-side errors (5xx, 4xx responses)
2. ConnectionFailure - Network connectivity issues
3. DevelopmentFailure - Development-time errors and bugs
4. ClientFailure - Client-side validation and logic errors
5. Use specific failure types for different error scenarios
6. Implement proper error mapping from exceptions to failures

Custom Failure Types

1. Create specific failure types for different error scenarios
2. Implement proper error context and additional data
3. Use failure extensions for common operations
4. Implement proper error serialization for logging

Error Handling Patterns

Repository Pattern Error Handling

1. Use safeCall wrapper for all network operations
2. Implement proper error mapping from exceptions to failures
3. Handle different error types appropriately
4. Provide fallback mechanisms for critical operations
5. Use proper error propagation through the call stack

Service Layer Error Handling

1. Implement proper error handling in service methods
2. Use repository error handling patterns
3. Provide meaningful error messages for business logic
4. Handle validation errors appropriately
5. Implement proper error recovery mechanisms

Network Error Handling

Dio Error Handling Rules

1. Use safeCall wrapper for all network operations
2. Implement proper error mapping from DioException to Failure
3. Handle different DioException types appropriately
4. Provide meaningful error messages for users
5. Implement proper error recovery mechanisms

Network Error Recovery Rules

1. Implement retry mechanisms for transient errors
2. Use exponential backoff for retry attempts
3. Handle connection failures gracefully
4. Provide offline fallbacks when possible
5. Implement proper error recovery strategies

UI Error Handling

Cubit Error Handling Rules

1. Handle errors in Cubit methods appropriately
2. Emit error states with proper error information
3. Provide meaningful error messages for users
4. Implement proper error recovery mechanisms
5. Use proper error logging with context

Widget Error Handling Rules

1. Handle error states in UI components
2. Provide user-friendly error messages and recovery options
3. Implement proper error boundaries for critical components
4. Use error widgets for consistent error display
5. Implement proper error recovery mechanisms

Form Error Handling Rules

1. Handle validation errors in form fields
2. Display field-specific error messages appropriately
3. Implement proper error recovery mechanisms
4. Use consistent error styling across forms
5. Provide clear error feedback to users

Logging and Monitoring

Error Logging Rules

1. Log errors with proper context and stack traces
2. Use appropriate log levels for different error types
3. Include relevant metadata in error logs
4. Implement proper error aggregation for monitoring
5. Use structured logging for better analysis

Error Monitoring Rules

1. Implement proper error tracking for production
2. Use crash reporting services for error monitoring
3. Track error rates and patterns
4. Implement proper error alerting for critical errors
5. Use error analytics for improvement

Common Violations

❌ DO NOT Violate These Rules

1. Don't ignore errors - Always handle errors appropriately
2. Don't use generic error messages - Provide specific, helpful messages
3. Don't expose technical details - Use user-friendly error messages
4. Don't forget error logging - Always log errors with context
5. Don't use try-catch without proper handling - Implement proper error handling
6. Don't ignore network errors - Handle network failures gracefully
7. Don't use empty catch blocks - Always handle caught exceptions
8. Don't forget error recovery - Implement proper error recovery mechanisms
9. Don't ignore validation errors - Handle validation failures appropriately
10. Don't use hardcoded error messages - Use localized error messages
11. Don't swallow exceptions - Always handle or rethrow exceptions
12. Don't ignore error states - Always handle error states in UI
13. Don't use print for errors - Use proper logging mechanisms
14. Don't forget error boundaries - Implement error boundaries for critical components
15. Don't ignore retry mechanisms - Implement retry for transient errors

✅ ALWAYS Follow These Rules

1. Use structured error handling with Failure classes
2. Implement proper error mapping for different error types
3. Use safeCall wrapper for network operations
4. Handle errors gracefully in UI components
5. Log errors appropriately with context
6. Provide meaningful error messages to users
7. Implement proper error recovery mechanisms
8. Use Result pattern for error handling
9. Handle different failure types appropriately
10. Implement proper error propagation through the call stack
11. Use proper error logging with stack traces
12. Implement error monitoring for production
13. Handle validation errors appropriately
14. Use proper error boundaries for critical components
15. Implement retry mechanisms for transient errors
16. Use exponential backoff for retry attempts
17. Handle connection failures gracefully
18. Provide offline fallbacks when possible
19. Use proper error recovery strategies
20. Implement proper error alerting for critical errors
21. Use user-friendly error messages in UI
22. Implement proper error state management in Cubit/Bloc
23. Handle errors at appropriate levels (UI, Service, Repository)
24. Use consistent error handling patterns across the app
25. Implement proper error serialization for logging
26. Use proper error context in error messages
27. Implement proper error aggregation for monitoring
28. Use structured logging for better analysis
29. Implement proper error alerting for critical errors
30. Use error analytics for improvement