Write error messages for the person at the front desk

Most software we get called in to fix has the same quiet problem. When something fails, the screen tells the person using it nothing they can act on. "Error 500." "Something went wrong." "Invalid request." The person at the front desk reads it, tries again, gets the same thing, and then does one of two things. They call someone, or they work around the system and write the job on a sticky note.

Both of those cost more than the bug. The call pulls a developer or an owner away from their own work. The sticky note means the record is now wrong, and nobody will know until a customer asks why their visit never got scheduled.

When we build internal tools and custom software for service businesses, we treat error messages as part of the product, not a leftover. This post covers how we write them, what each one needs, and how to find the bad ones already in your system.

Who reads the error

A developer reads an error to figure out what broke. The person at the front desk reads it to figure out what to do next. Those are different questions, and most error messages only answer the first one, badly.

The office manager does not care that a database query timed out. They care whether the booking saved, whether they should try again, and whether the customer on the phone needs to hear anything. If the screen cannot answer those three things, it has failed them, even if the logs are perfect.

So the first rule is to write the message for the person who will see it. In a dispatch screen, that is a dispatcher. In a field app, it is a tech standing in a driveway with one bar of signal. In a customer portal, it is a customer who does not know or care how your software works.

Technical detail still belongs somewhere. Put it in the logs, with a reference code the person can read out over the phone. The screen gets plain words. The log gets the stack trace.

What a useful error says

Every error message we write tries to answer three questions, in this order:

• What happened. Say it in the words the user already uses. "The visit was not saved" is better than "Request failed."
• What state things are in now. This is the part most messages skip. Did anything save? Did a text go out to the customer? Is the slot still held? If the user has to guess, they will guess wrong half the time.
• What to do next. One clear action. "Try again in a minute." "Call the customer back to confirm the time." "Send this code to support: R-4821."

Here is a before and after, close to one we rewrote. The details are made up, but the shape is real.

Before: "Error: unable to process request."

After: "The visit was not saved. The customer has not been texted and the time slot is still open. Try saving again. If it fails twice, write down the details and send support code R-4821."

The second one is longer. It is also the only one that lets the dispatcher keep working without calling anyone.

A few habits help:

Name the thing, not the system. Say "the visit," "the invoice," or "the customer record." Do not say "the entity" or "the object." Use the same names the rest of the screen uses.

Do not blame the user unless they did something wrong. "You entered an invalid date" is fine when the date really is invalid. It is not fine when the date was valid and the server fell over.

Keep the data they typed. If a form fails to save, the worst thing you can do is clear it. The user should be able to fix one field and press save again, not retype the whole job while the customer waits.

Say when it is safe to retry. If pressing the button again might create a second invoice or a second booking, the message has to say so, and the system should be built so a retry does not duplicate anything. If it is safe, say that too. People hesitate when they are not sure.

Errors that are not errors

Some of the most confusing messages are not failures at all. They are the system doing what it was told, without explaining why.

A tech cannot close a job because a required photo is missing. A dispatcher cannot book a slot because it falls outside the service area. An invoice will not send because the customer has no email on file.

These are rules, and rules need reasons. "Cannot close job" leaves the tech guessing. "Add at least one photo of the finished work before closing this job" tells them exactly what to do, and they can do it in thirty seconds.

When we write the rules into a system, we write the message for each rule at the same time. If nobody can explain the rule in one plain sentence, that is often a sign the rule itself needs another look.

Errors from outside services

Custom software for service businesses usually talks to other systems: a payment processor, a texting provider, a calendar, a phone system, a mapping service. Each of those can fail on its own schedule.

The raw message from those services is almost never right for your users. A payment processor might return a decline code that means something specific to a developer and nothing to an office manager. Pass that code to the logs, and show the user what it means for them: "The card was declined. Ask the customer for another card or take payment on site."

When an outside service is down, say so plainly and say what still works. "Texts are not sending right now. Bookings still save, and we will send the confirmation texts once the service is back." That one sentence stops a dozen people from trying the same thing over and over.

Finding the bad ones you already have

You probably do not need a rewrite of the whole system. Most of the bad messages in a tool come from a small number of places, and the people using it already know where they are.

A simple way to find them:

1. Ask the team. Ask the front desk, the dispatchers, and a couple of techs which messages they have learned to ignore or work around. They will have a list ready.
2. Look at your support requests. Any time someone asks "what does this mean?" or sends a screenshot of an error, that message goes on the list.
3. Search the code for generic text. Phrases like "something went wrong," "an error occurred," and "invalid request" are a good place to start. Each one is a spot where nobody decided what the user should see.
4. Trigger the common failures on purpose. Turn off the network on a phone and try to close a job. Submit a form with a missing field. Book a slot that is already taken. Read what comes back as if you were the person who has a customer on hold.

Fix the five messages that cause the most calls first. That is usually enough to notice a difference within a week.

Treat the message like the rest of the screen

An error message is the one screen a user sees when they are already having a bad moment. It deserves the same care as the booking form or the schedule view.

Write it in the user's words. Say what happened, what state things are in, and what to do next. Keep the technical detail in the logs where the people who need it can find it. Then go ask the person at the front desk which message they hate most, and fix that one today.