Domain Error Strategy

Layer 2: Design Choices

Core Question

Who needs to handle this error, and how should they recover?

Before designing error types:

• Is this user-facing or internal?
• Is recovery possible?
• What context is needed for debugging?

Error Categorization

Thinking Prompt

Before designing error types:

1. Who sees this error?

   • End user → friendly message, actionable
   • Developer → detailed, debuggable
   • Ops → structured, alertable

2. Can we recover?

   • Transient → retry with backoff
   • Degradable → fallback value
   • Permanent → fail fast, alert

3. What context is needed?

   • Call chain → anyhow::Context
   • Request ID → structured logging
   • Input data → error payload

Trace Up ↑

To domain constraints (Layer 3):

"How should I handle payment failures?"
    ↑ Ask: What are the business rules for retries?
    ↑ Check: domain-web or project requirements
    ↑ Check: SLA (availability requirements)

Trace Down ↓

To implementation (Layer 1):

"Need typed errors"
    ↓ m06-error-handling: thiserror for library
    ↓ m04-zero-cost: Error enum design

"Need error context"
    ↓ m06-error-handling: anyhow::Context
    ↓ Logging: tracing with fields

"Need retry logic"
    ↓ m07-concurrency: async retry patterns
    ↓ Crates: tokio-retry, backoff

Quick Reference

Error Hierarchy

rust
1#[derive(thiserror::Error, Debug)]
2pub enum AppError {
3    // User-facing
4    #[error("Invalid input: {0}")]
5    Validation(String),
6
7    // Transient (retryable)
8    #[error("Service temporarily unavailable")]
9    ServiceUnavailable(#[source] reqwest::Error),
10
11    // Internal (log details, show generic)
12    #[error("Internal error")]
13    Internal(#[source] anyhow::Error),
14}
15
16impl AppError {
17    pub fn is_retryable(&self) -> bool {
18        matches!(self, Self::ServiceUnavailable(_))
19    }
20}

Retry Pattern

rust
1use tokio_retry::{Retry, strategy::ExponentialBackoff};
2
3async fn with_retry<F, Fut, T, E>(f: F) -> Result<T, E>
4where
5    F: Fn() -> Fut,
6    Fut: Future<Output = Result<T, E>>,
7    E: std::fmt::Debug,
8{
9    let strategy = ExponentialBackoff::from_millis(100)
10        .max_delay(Duration::from_secs(10))
11        .take(5);
12
13    Retry::spawn(strategy, || f()).await
14}

Common Mistakes

Anti-Patterns

Related Skills