Write Useful Web Error Messages: Worked Workshop

This self-study workshop rewrites errors for a fictional draft editor. Your task is to distinguish what failed, what remains available and what someone can do next. You will produce a message table and a small deterministic selector using invented error codes. No real service failure, form submission or account is involved.

The W3C user-notification tutorial recommends concise, understandable feedback with instructions for resolving errors. It also explains the value of confirming successful completion, rather than reporting failures alone.

Write a message from the known state

The fictional editor has a title field and a local preview. A title must contain at least three characters after surrounding whitespace is ignored. The supplied practice model retains all entered text after a failed attempt. A separate invented event can make a requested practice guide unavailable. Do not infer a cause that the model does not provide.

The improved messages answer different questions. The first identifies a correctable value and preserves the draft context. The second provides an available alternative. The third avoids promising that a retry will succeed when the failure is unknown. The success message states the narrow action that actually finished.

Complete worked selector

The following original JavaScript is inert text. Its input is a fictional symbolic code and its output is a message string. It performs no request and changes no field. The surrounding application would still need to place the chosen message appropriately.

function explain(code) {
  if (code === "TITLE_SHORT") {
    return "Enter at least three title characters. Your draft remains available.";
  }
  if (code === "GUIDE_MISSING") {
    return "This practice guide is unavailable. Return to the local reading list.";
  }
  if (code === "PREVIEW_READY") {
    return "Local preview is ready. Nothing has been submitted.";
  }
  return "The local task could not finish. Keep your draft and return to the practice start.";
}

For the worked answer, explain("TITLE_SHORT") returns the first improved message exactly. explain("PREVIEW_READY") returns the local success message. Any unrecognised code, including an empty string, returns the final fallback. There is no path that claims a real submission occurred.

Test the fallback explicitly. A selector that handles the three familiar codes but returns no message for anything else would leave an important part of the contract unspecified. An unknown condition is not an invitation to invent a confident technical explanation.

Diagnose a message without overclaiming

Suppose a draft field still contains the title after a failed preview, but the message says it was lost. The wording would contradict the model state. Conversely, a message promising that a draft remains available is wrong if a handler has already reset it. Message quality and state handling must be checked together.

Another common problem is to include an internal code without an actionable explanation. A learner may need the code in a diagnostic record, but the message should still describe the relevant next step. In this exercise, the symbolic input belongs in the test table; the returned wording remains understandable on its own.

Now consider a hypothetical interrupted remote operation. The fictional facts supplied here do not establish whether a server accepted anything, because our model has no server. Do not reuse the local message “Nothing has been submitted” as a universal response to an uncertain network result. A different system would need its own state evidence.

For an extension, add an unsupported-format condition. Before writing code, specify the permitted formats, which current values remain available and what a successful correction would look like. Then write one rejected and one corrected test. This connects the message to a demonstrable recovery route instead of a vague instruction to try harder.

Questions and completion criteria

Submit the message table, three known-code outputs and the fallback output. A complete answer distinguishes a local preview from a real submission and never presents an unknown cause as established. This small language-and-state exercise does not validate a production site’s error handling.

This is an original INTIAU editorial self-study activity; no qualification is awarded. Use Courses or Contact for institutional information.

View the study diagram