Error Handling

Priority: P1 (HIGH)

Implementation Workflow

1. Define failures — Create domain-specific failures using @freezed unions (e.g., UnauthorizedFailure, OutOfStockFailure).
2. Return Either — Repositories return Either<Failure, T>. No exceptions in UI/BLoC.
3. Catch in Infrastructure only — Infrastructure catches exceptions (e.g., DioException) and returns Left(Failure). Never rethrow to UI.
4. Fold in BLoC — Use .fold(failure, success) in BLoC to emit corresponding states. Remove try/catch from BLoC.
5. Localize messages — Use failure.failureMessage (returns TRObject or localized string) for UI-safe text.
6. Log with stable templates — Use low-cardinality message templates; pass variable data via metadata/context.
7. No Silent Catch: Never swallow errors without logging or documented retry.
8. Crashlytics Routing: All UI/BLoC catch blocks MUST route errors via AppLogger.error(AppException.fromException(e).message, error: e, stackTrace: st) for observability and type-safe UI messages.

Repository & BLoC Examples

See implementation examples for repository error mapping and BLoC consumption patterns.