Content design: How to write any error message

Rhiannon Jones
Jul 16, 2018 · 4 min read

This is the story of how I became a little bit of an error message nerd — and how you could become one, too. One of us, one of us.

From Chrome’s “Aw, Snap!” or “He’s dead, Jim!” to GitHub’s famous 404, error messages are one of the ways we content designers make our own fun. But when they’re bad, they’re very bad – and when you have a lot to manage, rewriting them all can seem like a Herculean task.

When I joined Deliveroo last year, our error messages were an inherited part of a fast-moving, fast-growing product. They’d never been given much attention — written by a raft of different people, from engineers to product designers, at different times, in different ways. They were often a little confusing, created for scenarios that were out of date. The tone was regularly off-kilter, too. Abrupt when it should be warm, over-familiar when it should be calm.

This is no rare phenomenon. In fact, it’s been that way at almost every product or organisation I’ve encountered.

But error messages are structural necessities. They’re the nuts, bolts, sticky tape and blu-tack of content design. When they don’t do their job, everything else you’re trying to build falls down.

As a newly minted, enthusiastic content design team, we were gripped with a desire to shake the dust off these forgotten corners of the product. Build a clear, usable, appropriate and consistent experience. And make sure that when we fail, we fail gracefully.

So we rewrote every error message in our customer product. Here’s how we did it.

1. Classify your errors

This step involved spreadsheeting, screenshotting and colour coding. If you just craned forward and started rubbing your hands together — hello, friend.

The right tone for an error message depends on how the reader is actually feeling. A good proxy for this is how much time they’ve spent on the task so far. Have they only just opened the app? Or have they chosen what to order, entered card details, typed out a delivery address? Is the problem something they can actually fix? How much will it impact their experience?

With this in mind, we catalogued and then categorised errors in two ways:

System — failures on the part of the system. They include service outages, items sold out or orders declined.

User — generated by user error, such as an incorrect card number or delivery address, lack of internet connection.

Then, they’re classified by:

Partial — a failure that only affects part of the system, and won’t completely stop users from completing their journey. Say a user wants to order food from their favourite restaurant, but they find it’s closed. Although frustrating, they can still complete their journey by ordering from another restaurant, so this is a partial error.

Total — a failure that completely removes the user’s ability to finish a journey. This would include 500 errors or severe outages.

We audited all of our error messages, with the help of our engineers, until we had every existing error screenshotted, tagged, each scenario described and classified as System or User, and colour coded with Partial or Total.

Once you’ve finished this step, you’re 80% of the way there!

2. Grade them by impact

A simple way to do this is to plot all of your errors on a graph. One axis describes whether they’re Total, Partial, System or User. The other describes how much impact each error has.

We decided on three levels of severity – ‘Annoying’, ‘Enraging’ and ‘Totally horrific’.

3. Define an approach

Once you have your errors mapped, you can start to see natural groupings. From there, you can define a common approach for all the errors in that group.

We did it like this:


  1. Explain
  2. Add warmth

Make the problem easy to understand. Balance the user’s annoyance with warmth — maybe a joke, if that’s right for your product. A touch of reassurance, something light. Adding a little flash of humanity helps avoid robo-speak and keeps the interaction positive.

A hypothetical example of an Annoying message — Explain, Add warmth


  1. Explain
  2. Instruct

Make the problem easy to understand. Give the user clear instructions to combat ambiguity (and anxiety) about what happens next.

A hypothetical example of an Enraging error – Explain, Instruct

Totally horrific — system error only

  1. Apologise
  2. Resolve

When necessary, give an unqualified apology. Owning the problem makes the apology more genuine. Make it clear we’re working to resolve it as best we can.

A hypothetical example of a Totally Horrific error – Apologise, Resolve.

Using a framework like this makes the writing and review process faster and more reliable. It means your whole content team can nail consistency more easily, too. And it lifts the quality of the final content.

The new error messages haven’t been released, so you won’t see them in your Deliveroo app just yet.

We won’t measure the impact of the new messages in any hard sense, because they’re simple improvements — we don’t expect them to move the needle in any significant way. But we will look for them to help our overall user experience become more grown-up, more solid and more stable.

Are you also an error message nerd? Join us — we’re hiring!

Deliveroo Design

Stories, tidbits and musings from the content, research and…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store