Key takeaways
- Expected rejection means the system is working, not broken.
- Retry advice is safe only when repetition cannot duplicate or corrupt work.
- Partial completion needs reconciliation, not a generic apology.
- User messages and internal records serve different audiences.
“Something went wrong” throws away the most useful fact: what sort of wrong? A blank required subject is not the same as an unavailable relational datastore. A saved request followed by a failed notification is not the same as no saved request. Good handling begins with classification.
Use four questions. Was this outcome expected? Did durable state change? Is repeating the action safe? What can the user act on without seeing internal details? The answers choose the message and the recovery path.
Expected rejection: explain the rule
A request with an end before its start should be rejected. So should an illegal state move. The project is healthy; it is defending an invariant. Tell the user which input or current state blocks the action and what they can change. “Choose an end after 14:30” beats both “invalid input” and an internal parser message.
Keep rejected input available when safe, so correction does not require retyping. Never echo secrets. Field-level messages should connect to the field in accessible text, while a summary can help keyboard users find several errors.
Dependency failure: preserve uncertainty
If storage is unavailable before any write, the project can say the request was not recorded and suggest trying later. But when the write result is unknown because the response vanished, “not recorded” may be false. The honest message is: “We could not confirm whether the request was recorded. Check the list before trying again.”
That distinction matters because a blind retry can duplicate work. A uniqueness rule or attempt identifier can make repetition safe. Without one, tell the user how to check first. Logs may include operation, elapsed time, dependency category and a correlation value, but user copy should not expose host names, queries, traces or raw identifiers.
Partial completion: reconcile the split
Imagine the request was saved, then a non-essential message could not be queued. Rolling back the request may be worse than keeping it. The interface should say the request exists while the secondary action is delayed. Internal handling can mark that action pending and retry it safely.
If two writes must stand or fall together, use an atomic boundary where the storage design supports it. If they cross independent dependencies, plan compensation or reconciliation. “Try again” is dangerous when half the work already happened.
The original decision matrix
| Class | Durable change | Repeat? | User message | Internal evidence |
|---|---|---|---|---|
| Expected rejection | No | After correction | Name the rule and fix. | Rule code; no alert by default. |
| Dependency unavailable before write | No | Later | Not recorded; try later. | Dependency category and timing. |
| Write outcome uncertain | Unknown | Check first | Could not confirm; inspect list. | Attempt correlation and timeout point. |
| Partial completion | Yes, partly | Only failed subtask | State what succeeded and what is delayed. | Completed steps and pending work. |
| Unexpected defect | Unknown | Do not advise blindly | Action could not be completed; preserve input. | Safe context, revision and trace held privately. |
Do not turn this matrix into a public catalogue of internals. Its purpose is consistent decisions. Exact logging must be reviewed so that notes, personal details, credentials and secrets do not leak into diagnostic records.
Write messages from the next action backwards
A useful message contains three parts when known: what happened, what did not happen and what the user can do. It avoids blame. “That date is no longer available. Choose another date” is better than “You selected an invalid slot.” Short.
Messages should not claim success before durable confirmation. A pleasant green banner cannot repair an uncertain write. Likewise, do not show a retry control unless the repeated operation is safe. These are behaviour decisions, not merely copy decisions.
Verify the ugly paths
Induce each category in a controlled environment. Reject known bad values. Substitute an unavailable dependency. Force the secondary action to fail after the primary write. Simulate an uncertain response. Then observe stored state, user copy and private evidence. The risk-led verification plan gives these checks priority because failures are where false confirmations hide.
Link each case back to the state transition table and record invariants. The broader six-pass framework keeps those decisions aligned.
Honest limitation
This matrix is introductory. It does not establish incident response, secure logging, distributed recovery or legal notification duties. Security-critical, regulated, medical, financial, high-scale, real-time and safety-critical systems need specialist design and independent review.