The cause has to be in the message

What it is

Once the person knows the failure is real, the next sentence answers why it happened: the input broke a rule, the balance was short, the other party refused, or the server itself fell over. Cause exists to pick a recovery branch, not to write an incident report. When the cause is unknown, mark it unknown; “unstable network” is not a universal filler. This entry does not cover how the outcome is stated, nor what the fix control should say.

Why it happens

The same outcome maps onto recovery branches that are nothing like each other. An unpaid order may be a card decline, a limit, a merchant timeout, or a front end that never saw the receipt. Without a cause, people take the default branch—pay again—and either double-charge on a non-idempotent path or spin on a rule error. Cause splits one shade of red into dispatchable classes. Security and privacy limit how deep the sentence may go, but dispatch still needs enough grain: change the input, change the method, wait on the system, or get a human. A fabricated cause is worse than silence, because it sends them down a branch that is certainly wrong.

Studying it

Take one “submit failed” and inject four real causes (validation, permission, remote refusal, unknown). Give each group either the outcome sentence alone or outcome plus cause.

Independent variables: whether cause class is disclosed, whether disclosure matches the injected fault, whether unknown is written as a concrete guess. Dependent variables: whether the chosen recovery matches the true cause, wasted retries, edits aimed at the wrong object, rate of treating unknown as a network problem.

Do not instruct “please choose the next step from the cause”; that overstates the sentence. Let the main task continue and watch which path they take unprompted.

Where it stops holding

Where cause would help an attacker (attempts remaining, fraud thresholds, whether an account exists), stop at “this could not complete” plus a safe next step. When several causes stack, give the one blocking the task, not a list. Internal service names and exception classes are not causes: they cannot help anyone choose among four branches. Self-healing faults with no user-visible effect do not need a cause sentence inserted mid-flow.

Applying it

• Keep a dispatch table per failure class: validation / permission / balance or quota / counterparty refusal / system fault / unknown, each with a different next step. Ban a shared “try again later.”
• When cause is unknown, write that it is still uncertain, and offer still-safe acts (check status, keep the draft, ask for help with a reference). Do not pad with a guess that merely sounds specific.
• Write cause only to the grain that selects a branch: “the card issuer declined this card” is enough; the internal meaning of a decline code is not.
• Verify by firing the four faults at the same surface and watching whether the first move goes to edit, switch method, wait/query, or support. If all four roads hit the same button, cause is not dispatching.

Related

• Within the group: H3.02.1 Name the failed outcome before anything else · H3.02.3 Every error needs a next action · H3.02.4 Error codes are for support, not for the reader
• Adjacent: B3.09 Error recognition, diagnosis, and recovery · H3.10 Retry strategy · T2.04 Error copy
• Search terms: error cause · recovery branch · unknown cause