← All writing
/writing

A Refused Operation Is a Return Value, Not an Exception

Exceptions are for the unexpected. A business rule declining an operation is the most expected thing your system does.

The problem

if (!guard.IsSatisfied(context))
    throw new InvalidOperationException("Precondition not met");

Everything that made the refusal useful is now a string. The caller can't tell "not permitted" from "not yet" from "already done" without parsing prose, so the API layer collapses all of it into one status code — usually 400, sometimes 500.

Model the outcomes

public enum Refusal { NotPermitted, PreconditionUnmet, NoSuchTransition, Conflict }
 
public sealed record TransitionOutcome(
    bool Succeeded,
    Refusal? Refusal = null,
    IReadOnlyList<GuardResult> Failures = null);

Each refusal now maps to a distinct HTTP response — 403, 422, 404, 409 — and the failures carry which rules were unmet and why.

Why it matters

Two things fall out of this that you don't get from exceptions.

The API layer becomes a translation, not a decision. It maps an enum to a status code; it isn't inferring intent from an exception type someone chose in a hurry.

And you can evaluate all the rules instead of stopping at the first. A user fixing three problems one refusal at a time will submit three times and resent you for it. Return the whole list.

Keep exceptions for the genuinely exceptional: the transition row naming a rule that doesn't exist. That one should explode.

← All writing