skip to content

In a payroll product's content style guide, what structure should an error message follow, for example when a pay run fails validation?

level: middleimportance: must knowfreq 38%

answer

  1. three parts, in order
  2. specific to the item
  3. plain words, not system terms
  4. no blame, a way forward
  5. Error Identification, Error Suggestion

basics

~20 s

Say what happened in plain words, specific to the item; say why if it helps; and say how to fix it or what to do next. Avoid bare codes, blame and a vague 'Something went wrong'.

solid answer

~50 s

I use three parts. **What happened**, specific to the item: 'This pay run can't be approved.' **Why**, when it helps the user act: '3 employees have no bank details.' **How to fix it**, naming the items: 'Add bank details for Ana Silva, Tom Reed and Priya Nair, then approve again.' The words are the user's, not the system's - no 'validation failed' or 'null value' - and there is no blame: 'no bank details' rather than 'you failed to enter'. Codes can follow as a reference for support but never replace the message. For failures the user cannot fix, the message says whether their work is safe and what to do next. WCAG 2.2 backs this: 3.3.1 Error Identification (Level A) asks that the item in error be identified and the error described in text, and 3.3.3 Error Suggestion (Level AA) asks for known corrections to be offered.

go deeper

for a junior

Write errors in three parts - what happened, why if it helps, how to fix it - specific to the item, in plain words and without blame.

for a middle

Explain how the structure adapts to field errors, task errors and system failures, and how it meets WCAG 2.2 3.3.1 Error Identification and 3.3.3 Error Suggestion.

for a senior

Show how you would audit a product's error strings, give engineers templates and banned phrasings, and review errors in high-stakes flows such as approving a pay run.

for a principal

Weigh how much error wording to centralise in shared templates against letting teams write for their own domain, and how to fund ongoing review.

## The three parts An **error message** exists to get the user from a problem back to their task. Most content style guides give it a fixed structure: 1. **What happened** - the problem, specific to the item: 'This pay run can't be approved.' 2. **Why** - the cause, when knowing it helps the user act: '3 employees have no bank details.' 3. **How to fix it** - the next step, as concrete as possible: 'Add bank details for Ana Silva, Tom Reed and Priya Nair, then approve again.' Not every message needs all three at full length. A field-level message can merge them - 'Enter a tax code in the format 1257L' - while a failure at the level of the whole pay run needs each part spelled out. The order matters: what first, so the user knows whether this concerns them; the fix last, so it is what they remember. ## A worked payroll example | Weak message | What is wrong | Stronger message | |---|---|---| | Error 422: validation failed | System terms, no fix | This pay run can't be approved: 3 employees have no bank details. | | Something went wrong | Says nothing | We couldn't calculate tax for Tom Reed because his tax code is missing. Add a tax code to continue. | | You entered an invalid date | Blames, vague | The pay date must be a working day. Choose a date on or before 28 March. | | Invalid input | Which input? Why? | Enter a salary above 0. | The stronger versions are sometimes longer, but every extra word does work. ## Rules that make messages work - **Be specific.** Name the field, the employee or the pay run, not 'some items'. - **Use the user's words.** 'Bank details', not 'payment instrument'; 'tax code', not 'TC field'. Use the terms from the product glossary. - **No blame.** Describe the state, not the person: 'The pay date is a holiday', not 'You chose a holiday'. - **Offer the fix.** If the product knows the valid range or format, say it. - **Keep the user's work.** Say so when their input is kept: 'Your changes are saved.' - **Codes are secondary.** An error reference can follow the message for support staff, never replace it. - **One message, one problem.** When several things are wrong, list them rather than merging them into a vague summary. ## What WCAG 2.2 requires Two success criteria set a floor for error text: - **3.3.1 Error Identification (Level A):** if an input error is automatically detected, the item in error is identified and the error is described to the user in text. A red outline alone does not meet this. - **3.3.3 Error Suggestion (Level AA):** if an input error is detected and suggestions for correction are known, they are provided, unless doing so would jeopardise the security or purpose of the content. A password check, for example, may not reveal what the correct value is. The structure above meets both by design: the 'what' identifies the item, the 'how to fix it' carries the suggestion. ## When the user cannot fix it Some failures are the system's, not the user's: a service outage, a bank connection timing out. The structure adapts: - say what happened in plain words - 'We couldn't reach the bank to send payments'; - say what is safe - 'Your pay run is saved and nobody has been paid yet'; - say what to do - 'Try again in a few minutes. If it keeps happening, contact support with reference 7F3A'. The second point is often the most important sentence for a payroll manager, whose first fear is double or missing payments. ## Templates in the style guide Because engineers write most error strings, the style guide should give templates, not just principles: a pattern for field errors, one for whole-task errors and one for system failures, each with two or three real examples from the product. Pair them with a list of banned phrasings - 'invalid', 'illegal', 'fatal', 'Oops' - and a review step for errors in high-stakes flows such as approving and paying a pay run. Where the message appears on screen and how its tone shifts are decided by the form patterns and the tone guidelines; the style guide owns the words and their structure.

  • When several fields in a pay run are wrong at once, how should the messages be written?
    One message per problem, each naming its item and fix, plus a short summary that states how many problems there are - '3 employees need attention before approval' - with each listed. Merging them into one vague line forces users to hunt. The summary tells them the size of the job; the item messages tell them what to do.
  • Where do error codes belong, if anywhere?
    After the human message, as a reference for support - 'If this keeps happening, contact support with reference 7F3A.' A code helps support staff find the log entry; it helps the user only when paired with plain words. A message that is only a code falls short of the intent of WCAG 2.2 3.3.1, which asks for the error to be described to the user in text.
  • Why should error messages use the product glossary's terms?
    Because users match the words in the message to the words on the screen. If the form says 'bank details' and the error says 'payment instrument', users wonder whether they are different things and cannot find the field. Consistent terms turn the message into a direct pointer to what needs fixing.

saying these in an interview costs you the question

  • 'Something went wrong' is fine because users do not need details.
  • An error code alone is enough, since support can look it up.
  • Error messages should state what the user did wrong.
  • Outlining the field in red is enough to identify the error.
  • Every error message must explain the technical cause in full.