Prompt AI to Write Error Messages Users Can Act On

To prompt AI to write error messages that help, give it the list of real failure cases from your app and tell it to write only from that list. Left alone, a model will happily explain why something failed using a cause that never happened, and a confident wrong explanation is worse than "something went wrong". Pair that rule with a clear target for each message: say what happened, and say what the person can do next.

Most apps built quickly with AI ship with defaults like "Error", "Invalid input" or a raw stack trace in a red box. Fixing them is some of the cheapest polish available.

What a good error message does

Guidance from usability researchers is consistent. Nielsen Norman Group's error message guidelines describe messages that use human-readable language, are concise and precise, offer constructive advice and do not blame the user. The GOV.UK Design System's error message component is more specific about wording: describe what has happened and tell the person how to fix it, in plain English.

It also splits messages by the kind of problem, and that split is the best structure to give an AI:

• Empty field: an instruction, like "Enter your first name."

• Breaks a rule: state the rule, like "Name must be 35 characters or less."

• Wrong format: be specific about the format that is expected.

The guidance also notes that words like "sorry", "please" and "invalid" add nothing useful. That is a good line to copy into your prompt.

Six rewrites

Here is what the shift looks like on messages found in typical AI-generated apps.

None of the "after" messages blame the person, and none contain a joke or an apology. The apology is the first thing a model adds, and the first thing worth deleting.

How to prompt AI to write error messages: the brief

The most important part of the prompt is the input. Give the model your real failure cases, not a request to imagine some.

You write error messages for a booking app. Plain English, under 20 words
each, no apologies, no "invalid", no exclamation marks.
For each case below, write one message that says what happened and what
the user should do next. Only use the cause I give you. If the cause is
unknown, say so honestly and give a safe next step.

Cases:
1. Card payment returns code card_declined
2. Session token expired (HTTP 401)
3. User picks a booking slot that was taken a second ago
4. Upload larger than 5 MB
5. Server timeout while saving
6. Email field left empty

The line "only use the cause I give you" does the real work. Without it, case 5 comes back as "Our servers are overloaded", which you do not know to be true.

Get the list of cases from the code, not from memory. Ask the AI coding agent to list every place the app can show an error, which also tends to turn up the places where errors are swallowed silently; stopping an AI coding agent from swallowing errors covers that problem. For server failures that users see as a blank page, what a 500 error is in an AI-built app explains where to look.

Where the model goes wrong

Three failures show up again and again. It invents a cause, as in the server timeout example. It shifts blame onto the person with phrases like "You entered an invalid date", when "Enter a date in the format 31/12/2026" says the same thing without the accusation. And it runs long, adding a second sentence of reassurance nobody asked for. Each of these is fixable with one line in the prompt, which is why it pays to keep the prompt in a file and tighten it after every batch.

Keep the finished messages in one place too, keyed by the error code, so changing the wording never means touching the logic:

export const messages = {
  card_declined: "The card was declined by your bank. Try another card or contact your bank.",
  session_expired: "Your session has ended. Log in again to continue.",
  slot_taken: "That time was just booked. Pick another slot.",
} as const;

This also makes review easy: one file, every message, readable in two minutes.

Checking the output

Read every message as if you were tired and in a hurry. Then run four checks:

1. Does it say what happened? If you cannot tell, a user cannot either.

2. Does it say what to do? Even "try again in a minute" counts.

3. Is any word doing no work? "Oops", "unfortunately" and "sorry" can go.

4. Is it true? Compare it to the actual error code. This is the check that AI most often fails.

Then look at where the message appears. A message placed far from the field it refers to is hard to connect to the problem, and a screen reader user may never hear it. Placing the message next to its field and linking it correctly is part of making an AI-built app accessible. Empty screens deserve the same care as error ones; see empty states in an AI-built app.

For the broader skill of briefing a model with constraints rather than adjectives, the prompt engineering guide is a good next read.

Frequently asked questions

Should error messages be funny?

Rarely. Someone who has just lost work or been refused a payment is not in the mood for a joke. Plain and useful is the safer register.

How long should an error message be?

As short as it can be while still saying what happened and what to do. Under about 20 words covers most cases, with a link for the rare case that needs more.

Can AI translate error messages into other languages?

It can produce a good draft, but have a speaker check any message about money, deletion or legal rights, since a small mistranslation there matters more than elsewhere.

Why does the AI keep adding "Sorry" to every message?

Models are trained on a lot of customer service text. Add "no apologies" to the prompt and delete any that slip through.