What error message would you write for a model timeout, and what would you avoid saying?

SkyQuery is an AI flight search assistant that lets travelers describe a trip in plain language instead of filling in a rigid form. Franklin Osei writes the product's user-facing copy. Here is the exact message SkyQuery showed when its search model timed out, and what a real audit of that message actually found.

How to answer this, stage by stage

Nobody is grading whether you can write a nicer sentence. They're grading whether you can judge the one that's already live before you touch it.

Let's learn

SkyQuery is a flight search tool that reads a loose request, "cheapest way to Lisbon in October, no red-eyes," and searches across many partner airlines and fare combinations to answer it, instead of forcing a traveler into a rigid origin, destination, and date form.

The message was never written for a traveler. It was written for a log file, and nothing ever stood between the two.

Before SkyQuery's flexible search, travelers used a basic form with fixed fields, slower to fill out, but it always returned a result list in under two seconds, since there was no open-ended question for a model to think through.

Here's the turn: the flexibility itself was never the problem. As more travelers typed in loose, multi-city, flexible-date questions, more searches ran long enough to time out, and the message that greeted them when that happened had never been written for a traveler at all. It was the exact string an engineer would see in a server log, sent straight to the screen with nothing translated in between.

At its worst, a traveler reads "retry_code=504," assumes the worst, closes the tab, and books directly on an airline's own site instead, at a higher fare, simply because a string built for a log file made a normal timeout look like a serious failure.

Same failure, same server, same twelve seconds. Only what the traveler was told about it changed.

What I would leave alone: the fast, simple searches that never time out don't need any of this. This message only exists for the rare slow query, and nothing here should touch the common, quick path.

The lesson: an error message is the one piece of copy a product writes for someone who is already anxious. It's the worst possible place to leave in a sentence meant for a different reader.

Now here is the same thing as a story

The short version above is what you'd say defending this rewrite to SkyQuery's product council. Read this one for how the message survived unnoticed for as long as it did.

Franklin writes most of the words a traveler sees on SkyQuery, confirmation screens, empty states, the little reassurances that show up when a search is running. For a long time, the timeout message wasn't on anyone's list to review, since it almost never fired.

As SkyQuery's flexible search grew popular, more loose, multi-city, flexible-date questions came in, and more of them ran long enough to hit the model's timeout. Nobody had been tracking that number on its own, since it lived buried inside a broader "search success rate" that still looked mostly fine.

Three weeks between the raw message quietly reaching real travelers and anyone on the team asking why it said what it said.

A new hire on the support team, going through a backlog of tickets in her second week, asked in a channel: "why does our timeout error say 'retry_code=504'? What is a traveler supposed to do with that?" Nobody had a ready answer. It had simply never been anyone's job to notice.

Franklin pulled the actual message and sat with it the way a traveler would, mid-search, phone in hand, trying to book a trip before a fare changed. Read cold, it gave no next step, no word on whether a charge had gone through, and a string of characters that looked, to anyone outside engineering, like proof something had badly broken.

All three gaps existed in the exact same twelve words. None of them required a single change to how the search itself works.

With the redesigned message, a timeout now reads: "Your search took too long and timed out. You weren't charged. Try again, or narrow your dates to speed it up." Run the same search forward: the traveler who once closed the tab in frustration now taps "try again," narrows her dates, and gets a result in under ten seconds.

The old message answered none of these four questions. It answered a question nobody standing at a gate was actually asking.

The old message told a traveler exactly what an engineer needed to know. The new one tells her exactly what she needs to know instead.

We let that raw string ship because it was never meant to last, just a placeholder for a feature still finding its feet. It took a new hire's plain question to notice that "temporary" and "shipped to thousands of travelers a week" had quietly become the same thing.

AUDIT, aimed at a single error messageNot a style guide for cheerful copy. AUDIT is what forces you to judge the exact words already on screen before writing new ones.

A timeout is exactly the kind of error where the traveler can genuinely act. That's what earns it a specific, confident message instead of a vague one.

The recap, one line per letter: ask who it serves finds the audience mismatch, uncover what actually failed separates the real cause from the code, demand a next step gives the traveler something to do, isolate what's missing names the three gaps plainly, and test it yourself checks the rewrite against a real, anxious reading.

And if you want to be sure it really works, try it somewhere elseSame five letters, a hotel's overbooking notice instead of a flight search timeout. A different failure, the same audit.

Cordova Stays runs a booking platform where an overbooking-prevention model occasionally has to tell a guest their exact room type sold out after they'd already booked it. Nadia Fitch handles guest relations for the chain. Mapped onto AUDIT: the old message read "Inventory conflict: SKU unavailable, booking reference invalidated," written for the reservations system, not the guest holding a confirmation email.

Asking who it serves finds the same mismatch: an internal inventory term, not a guest's actual situation. Uncovering what failed means naming that a genuine double-booking happened, not implying the guest did anything wrong. Demanding a next step means the message has to offer a specific alternative room or a full refund path, immediately, not just an apology. The redesigned message reads: "We're sorry, your exact room type sold out due to a booking conflict on our end. We've held you an upgraded room at no extra cost, or you can cancel for a full refund." Testing it cold, as a guest who already packed a bag, is what caught that the first draft still buried the refund option two screens deep.

Swap "were you charged" for "here's your room or your refund," and the same four parts still do the same job.

Swap the trigger and it still runs.
Speed: an interviewer caps you at sixty seconds. Say "plain words, a reassurance, one next step, no internal codes, no blame," and stop.
Cost: there's no engineering time to build a different message for every possible internal error code this quarter. Say so honestly, and start with the errors travelers actually hit most, timeouts and payment failures, before covering every rare internal case.
The model gets better, for real: if SkyQuery's search speed genuinely improves and timeouts become rare, that's still not a reason to let the raw string creep back in, the rarer the error, the more surprising and alarming an unexplained code will read.

Where people run it wrong.
They treat error copy as an engineering afterthought instead of the one moment a product writer should care about most.
They add a friendlier tone to the same unhelpful content, instead of actually giving the person a next step.
They promise certainty they don't have, "this will never happen again," which reads as hollow the second time it does.

How to use it live. When someone hands you an error message and asks if it's good, read it once as the exact person who'll see it, mid-task, a little anxious, and ask whether it tells them what happened, whether they're safe, and what to do next. If it's missing any of the three, it isn't ready.

Flashcards (tap any card to flip it)

Check yourself Score: 0 / 0