Skip to content
DocumentationHandle failures
On this page

Page resources

Open Markdownllms.txtView source

Last updated

Handle failures without flattening them

This recipe shows the dispositions an application keeps separate from domain fault through distributed execution and recovery.

The Rust and JSON APIs below are illustrative end-product examples.

1. Match the complete result

Rust
match client.orders().place(request).await {
    OperationResult::Succeeded(order) => show_order(order),
    OperationResult::Rejected(fault) => show_domain_fault(fault),
    OperationResult::Denied(denial) => request_access(denial),
    OperationResult::Cancelled(cancel) => show_cancelled(cancel),
    OperationResult::OutcomeUnknown(effect) => offer_reconciliation(effect),
    OperationResult::Unsupported(requirement) => explain_unsupported(requirement),
    OperationResult::Unsatisfied(proof) => explain_missing_realization(proof),
    OperationResult::Incompatible(details) => require_upgrade(details),
    OperationResult::Defect(defect) => report_defect(defect),
    OperationResult::Failed(failure) => show_recovery(failure),
}

Succeeded is the only success variant. Every outer class above is distinct and must be matched explicitly; a domain fault is carried by Rejected and is never collapsed into Failed. The failure model defines the intended names each language projection maps to.

2. Preserve nested causes

JSON
{
  "kind": "failed",
  "stage": "communication",
  "fault": "deadline_exceeded",
  "cause": {
    "kind": "provider_failure",
    "provider": "acme_carrier.provider#AcmeShipmentCreate@1",
    "attempt": "provider-attempt:sha256:32a1…"
  },
  "effect": {
    "state": "outcome_unknown",
    "reference": "effect:sha256:77c2…"
  }
}

A communication timeout cannot erase that an external effect may have been accepted.

3. Aggregate partial results honestly

Rust
let report = BatchResult {
    succeeded: vec![order_1, order_2],
    rejected: vec![(order_3, invalid_address)],
    unknown: vec![(order_4, effect_ref)],
    cancelled: vec![order_5],
};

One failed member does not rewrite completed members, and a summary count does not replace per-item evidence.

4. Test negative paths

Console
one test --root OrdersApi --scenario authority-revoked-after-check
one test --root OrdersApi --scenario cancellation-after-dispatch
one test --root OrdersApi --scenario provider-response-lost
one test --root OrdersApi --scenario stale-evidence
one test --root OrdersApi --scenario unsupported-target
one test --root OrdersApi --scenario bounded-batch-partial-failure

See the failure model and recovery and continuity.