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

Error Type Audience Recovery Example

User-facing End users Guide action InvalidEmail , NotFound

Internal Developers Debug info DatabaseError , ParseError

System Ops/SRE Monitor/alert ConnectionTimeout , RateLimited

Transient Automation Retry NetworkError , ServiceUnavailable

Permanent Human Investigate ConfigInvalid , DataCorrupted

Thinking Prompt

Before designing error types:

Who sees this error?

• End user → friendly message, actionable

• Developer → detailed, debuggable

• Ops → structured, alertable

Can we recover?

• Transient → retry with backoff

• Degradable → fallback value

• Permanent → fail fast, alert

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-fintech (transaction requirements) ↑ Check: SLA (availability requirements)

Question Trace To Ask

Retry policy domain-* What's acceptable latency for retry?

User experience domain-* What message should users see?

Compliance domain-* What must be logged for audit?

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

Recovery Pattern When Implementation

Retry Transient failures exponential backoff

Fallback Degraded mode cached/default value

Circuit Breaker Cascading failures failsafe-rs

Timeout Slow operations tokio::time::timeout

Bulkhead Isolation separate thread pools

Error Hierarchy

#[derive(thiserror::Error, Debug)] pub enum AppError { // User-facing #[error("Invalid input: {0}")] Validation(String),

// Transient (retryable)
#[error("Service temporarily unavailable")]
ServiceUnavailable(#[source] reqwest::Error),

// Internal (log details, show generic)
#[error("Internal error")]
Internal(#[source] anyhow::Error),

}

impl AppError { pub fn is_retryable(&self) -> bool { matches!(self, Self::ServiceUnavailable(_)) } }

Retry Pattern

use tokio_retry::{Retry, strategy::ExponentialBackoff};

async fn with_retry<F, T, E>(f: F) -> Result<T, E> where F: Fn() -> impl Future<Output = Result<T, E>>, E: std::fmt::Debug, { let strategy = ExponentialBackoff::from_millis(100) .max_delay(Duration::from_secs(10)) .take(5);

Retry::spawn(strategy, || f()).await

}

Common Mistakes

Mistake Why Wrong Better

Same error for all No actionability Categorize by audience

Retry everything Wasted resources Only transient errors

Infinite retry DoS self Max attempts + backoff

Expose internal errors Security risk User-friendly messages

No context Hard to debug .context() everywhere

Anti-Patterns

Anti-Pattern Why Bad Better

String errors No structure thiserror types

panic! for recoverable Bad UX Result with context

Ignore errors Silent failures Log or propagate

Box everywhere Lost type info thiserror

Error in happy path Performance Early validation

Related Skills

When See

Error handling basics m06-error-handling

Retry implementation m07-concurrency

Domain modeling m09-domain

User-facing APIs domain-*