Summary: Technical error messages are not stories, no matter how much we squint at them. They’re blunt interruptions in a flow of interaction—especially for users hoping to extract useful or narrative content. This post unpacks the real limits of trying to turn a JSON error message into a coherent story, highlights why such attempts fail, and explains what this tells us about communicating effectively in tech environments.
Error Messages: The Misunderstood Interrupters
Someone once said that every error holds a story. That might work in literature or courtrooms, but it breaks down painfully fast when you’re presented with a JSON object like this:
{
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "Your account balance is too low to complete this transaction."
}
}
Let’s not romanticize this. It’s not Kafka. It’s not Hemingway. It’s not even a story. It’s a simple, blunt instrument—a structured, machine-readable failure signal saying: “You can’t do that because you don’t have enough money.”
Why It’s Not a Story—and Never Was
A story needs characters, conflict, and some progression. That JSON error has none of that. No protagonist, no antagonist. No setting. No plot. It’s a dead end. Trying to extract narrative from it is like trying to pull music from a dropped phone call.
And doing so doesn’t just miss the point— it confuses your audience. Users don’t need embellishment when facing an account issue; they need facts, action steps, and clarity. Which begs the question:
How often does your messaging try to tell a story where brutal clarity should reign?
The Real Problem: Mistaking Signals for Substance
When technical systems speak, they don’t wax poetic. They give us structured data because they’re optimized for efficiency. The mistake many communicators make is treating those data structures as incomplete stories—fragments needing “rewriting.” That’s a strategic misfire.
Let’s mirror what developers actually need: reliability, transparency, and low-friction messaging. Process over prose. Certainty over suspense. Fictionalizing errors just wastes everyone’s time and breeds ambiguity. So let’s acknowledge the real problem: a JSON error isn’t a communication failure—it’s our broken expectation that a story was coming.
Reframing: What’s the Function of This Error?
The real question is not, “Can this be made into a story?” It’s:
“What function does this response serve—and how can I use that to improve user trust and product flow?”
That JSON error exists to inform and prevent confusion at the point of action. It’s a gateway message—not the story, but a hinge that determines what happens next. Recognizing that can completely shift how your team handles UX communication. Rather than force narrative, clarify decision trees. Use the moment to reinforce trust: if the system acts with integrity by stopping a transaction due to low balance, the next message should preserve that trust.
Clarity Over Creativity in Technical UX
Creativity isn’t your enemy—but in error messages, clarity comes first. Want to build stronger user experience systems? Start by encouraging clear functional communication and applying a storytelling mindset only where it naturally belongs—in longer onboarding flows, case studies, or brand narratives.
When you muddy a technical warning with story elements, you confuse roles. That JSON object wasn’t sent to entertain—it was meant to correct a process and protect the user from making a failed transaction. That is a feature worth emphasizing, not rewriting into a false narrative.
The Takeaway: Every Message Has a Purpose—Don’t Hijack It
Misapplying storytelling to technical communication does more harm than good. It risks clarity, introduces doubt, and can spin your team into wasted cycles reworking things that already work. The real emotional lift lies in acknowledging user frustration, not fictionalizing the system’s response.
Here’s a better approach:
- Acknowledge user frustration clearly – “We couldn’t complete the request because of a low account balance.”
- Identify what the user controls – “Please check your account balance or add funds to try again.”
- Preserve trust through precision and tone—do not add unnecessary narrative weight to functional logic.
So What Should You Do With These Messages?
How do you make these moments count even though they’re not stories?
You treat them as high-value decision points. If “No” is the system’s response, treat it like Chris Voss would: as the start of renegotiation. Invite the user to consider alternatives. Create micro-paths they can follow. Make your interface the beginning of their next action, not a literary monologue. That’s not poetic—but it’s powerful.
Final Note: Selling complexity with simplicity is what good communicators do. But selling clarity with false complexity? That’s an amateur move. Don’t waste time pretending a silent machine is secretly reciting a tale. Let data be data. Teach your user what it means. Help them act on it.
#TechCommunication #UXDesign #ErrorMessages #FunctionalWriting #ClarityOverCreativity #UserMessaging #SoftwareUX #StructuredCommunication
Featured Image courtesy of Unsplash and Minseok Kwak (GIttmwa7K74)
