When to Use Result Types

// Decision Flowchart for Error Handling
 
START: Operation might fail or return nothing
 
├── Q1: Is this a programming error or invariant violation?
│   └── YES → throw Exception (or panic)
│       Examples: null dereference, index out of bounds, assertion failure
│
├── Q2: Is failure expected in normal operation?
│   ├── YES → Continue to Q3
│   └── NO (truly exceptional) → throw Exception
│       Examples: out of memory, disk full, network unreachable (sometimes)
│
├── Q3: Does absence imply failure or just "nothing"?
│   ├── Just "nothing" (no error implied) → return Option<T>
│   │   Examples: find in map, first element, parent of root
│   └── Failure (something went wrong) → Continue to Q4
│
├── Q4: Are there multiple distinct error cases?
│   ├── YES → return Result<T, ErrorEnum>
│   │   Examples: validation errors, NOT_FOUND vs DB_ERROR
│   └── NO (single failure mode) → return Result<T, E> or simple error
│
└── Q5: What does your ecosystem expect?
    ├── Rust → Always Result/Option (no exceptions)
    ├── Go → Always (value, error) tuple
    ├── Kotlin/Swift → Nullable types with sealed classes for complex errors
    ├── TypeScript → Consider: strict null checks + Result unions
    └── Java/Python → Exceptions are idiomatic, but Result types gaining traction

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// Well-designed API with appropriate error types
 
// Validation: Result with detailed errors
pub fn validate_email(input: &str) -> Result<Email, EmailValidationError> {
    if input.is_empty() {
        return Err(EmailValidationError::Empty);
    }
    if !input.contains('@') {
        return Err(EmailValidationError::MissingAt);
    }
    // ... more validation
    Ok(Email::new_unchecked(input))
}
 
// Repository: Result distinguishing error types
pub trait UserRepository {
    fn find_by_id(&self, id: UserId) -> Result<User, FindError>;
    fn find_by_email(&self, email: &Email) -> Result<Option<User>, DbError>;
    //                                        ^^^^^^^^^^^^^^^^
    // Note: Option inside Result! This means:
    // - Ok(Some(user)): Found the user
    // - Ok(None): No user with that email (not an error)
    // - Err(e): Database error occurred
    
    fn save(&self, user: &User) -> Result<(), SaveError>;
}
 
#[derive(Debug, Error)]
pub enum FindError {
    #[error("User not found: {0}")]
    NotFound(UserId),
    #[error("Database error")]
    Database(#[source] sqlx::Error),
}
 
// Lookup: Option when absence is normal
pub trait Cache<K, V> {
    fn get(&self, key: &K) -> Option<&V>;  // Miss is expected
    fn insert(&mut self, key: K, value: V) -> Option<V>;  // Returns old value
}
 
// Parsing: Result with informative errors
pub fn parse_duration(s: &str) -> Result<Duration, ParseDurationError> {
    // Returns Err with context about what was wrong
}
 
// Internal function: panic on invariant violation
fn process_validated_data(data: &ValidatedData) {
    // This function's contract requires data to be pre-validated
    // Panicking on invalid data is appropriate - it's a programming error
    assert!(data.is_valid(), "invariant violation: data must be valid");
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// Wrapping a panic-prone FFI library
fn safe_ffi_call(input: &str) -> Result<Output, FfiError> {
    // std::panic::catch_unwind converts panics to Result
    std::panic::catch_unwind(|| {
        unsafe { ffi_library::process(input) }
    })
    .map_err(|_| FfiError::Panic)
    .and_then(|result| result.map_err(FfiError::Library))
}
 
// Wrapping a fallible external crate
use external_crate::Client;
 
struct SafeClient(Client);
 
impl SafeClient {
    fn fetch(&self, url: &str) -> Result<Response, FetchError> {
        // External crate might panic on invalid URL
        self.0.fetch(url).map_err(|e| match e.kind() {
            external_crate::ErrorKind::Network => FetchError::Network,
            external_crate::ErrorKind::Timeout => FetchError::Timeout,
            _ => FetchError::Unknown(e.to_string()),
        })
    }
}