Flat error messages are weak replay evidence

Teams often treat generic error handling as a presentation detail.

Something fails, a broad catch block turns the failure into one tidy application message, and the system moves on.

That may feel harmless when the message is only meant to keep the API response consistent.

In delivery systems, the message can do more than summarize. It can influence whether the next operator retries, replays, compensates, or leaves the request alone.

That is why flat error messages are weak replay evidence.

Replay depends on the boundary that actually failed #

A replay decision is never about failure in the abstract.

It is about where the uncertainty still lives.

If validation failed before any side effect began, replay is usually straightforward.

If persistence rejected the write after part of the workflow already committed, replay may duplicate work.

If the receiver accepted the request but the acknowledgement path failed later, replay may be the wrong recovery entirely.

A generic message like failed to process request or failed to create log collapses those very different states into one emotionally neat but operationally weak story.

The next person inherits a message that sounds final while hiding the boundary that matters most.

That person now has to guess whether the system stopped before the side effect, during it, or after it.

Guesses around replay are how ordinary incidents become expensive ones.

Flat messages create fake confidence #

A catch-all handler usually aims for consistency.

The problem is not consistent language.

The problem is consistent language that implies more understanding than the system actually has.

Suppose a worker catches a database exception, wraps it as delivery logging failed, and returns a single internal status to the dashboard.

That wording quietly steers the recovery path.

An operator may assume the delivery never reached the durable write it needed.

A support person may tell someone to retry.

An automated replay helper may treat the event like a harmless transient failure because the message sounds like bookkeeping, not delivery uncertainty.

The original exception may have been narrower, stranger, or more dangerous.

Maybe the payload exceeded a column limit after the request identity was already recorded.

Maybe the receiver accepted the handoff and the problem happened while storing metadata about it.

Maybe two side effects now disagree because the generic handler hid the split point.

Once the message becomes the most visible truth, the flattened story starts deciding recovery even though it was never strong enough to deserve that authority.

The system should preserve uncertainty, not erase it #

Good delivery records do not need dramatic prose.

They need the shortest honest description of the failure boundary.

Persistence write rejected.

Receipt lookup timed out after downstream acceptance remained unknown.

Response serialization failed after enqueue succeeded.

Those are not pretty messages.

They are useful because they tell the next operator which question still matters.

Did the side effect already happen.

Does a durable identifier exist.

Is replay safe, unsafe, or conditional on another lookup.

This is the same discipline reliable retry systems need elsewhere.

Timeouts should keep their doubt.

Dead-letter queues should keep their reason.

Incident records should keep the true boundary of failure long enough for a recovery decision to remain honest.

Replay should follow proof, not presentation #

A mature system separates two jobs.

One job is normalizing what the caller sees.

The other is preserving enough internal truth that operators can recover without folklore.

That means the user-facing response may stay simple while the operational record keeps the error class, request identity, side-effect state, and the next proof boundary needed before replay.

When those facts survive, the product can make safer decisions later.

Retry blocked until receipt lookup completes.

Manual replay allowed only with original request ID.

Do not retry automatically because downstream acceptance is unknown.

Those decisions come from evidence, not from the neatness of the last error string.

At Stack Dispatch we care about this because delivery reliability is usually lost in the handoff between uncertainty and recovery.

Flat error messages are weak replay evidence because presentation is not proof.

The message can stay simple.

The record beside it must stay honest enough that the next action is chosen from the real failure boundary rather than from a convenient fiction.