Summary: Not every text should be rewritten. Some are already stripped down to their function, and adding fluff doesn’t serve clarity—it clouds it. This is especially true with system-generated JSON error messages. When a message tells you your account balance is too low to complete an action, there is neither room nor need for narrative grandeur. Let’s break this down from a practical, technical, and marketing lens so readers stop wasting energy trying to “humanize” syntax that exists only to deliver raw facts.
Error Messages Aren’t Stories—They’re Signals
A JSON response about an error due to an insufficient account balance is not a broken poem. It doesn’t hide a character arc. It says what it says: your balance isn’t enough to complete the transaction. That’s it. Making it more complex won’t help your developer or your user—and could even mislead them.
Why do people try to extract a “story” from this kind of message? Because they’re conditioned—especially content creators and junior marketers—to believe everything needs context, drama, or emotion. But precision matters more in systems communication. The recipient of the message needs the following:
- What went wrong?
- Why it happened?
- What to do next?
A JSON object like:
{
"error": "insufficient_funds",
"message": "Your current balance is not enough to perform this transaction."
}
…already tells the user exactly what they need to know. No need to romanticize it. If anything, adding extra “narrative flair” would introduce ambiguity—which is a direct enemy of system efficiency and user trust.
The Purpose of Plain Formatting
Plain formatting isn’t laziness. It’s purposeful discipline. When systems fail, what we call “graceful degradation” depends on straightforward messaging. Plain formatting enables fast diagnostics—by a human or a machine. Here’s why clarity beats creativity in this case:
- Developers don’t need prose—they need output they can parse and respond to.
- End-users want to know what action to take. They’re already frustrated; don’t waste time sugar-coating.
- Support teams need just enough information to help without needing a translator.
Marketing Needs to Know Its Limits
This is where marketing needs to stop pretending every byte of output is a shot at emotional connection. If a product experience relies on fluff-filled error messaging, it’s compensating for a toxic UX—or worse, it’s hiding design failings behind “funny” alerts. This happens in startups often. It backfires more often than not.
Messaging without substance doesn’t build loyalty. And when money—like a failed payment—is involved, levity reads as mockery.
Let Simplicity Win
When systems throw messages like these, they’re acting responsibly. The message is:
“We looked at your balance. You don’t have enough. Nothing else can proceed.”
To rewrite or interpret that through a storytelling filter introduces risk. From a behavioral perspective (see Cialdini), this is a moment where users respond best to consistency and clarity. They want to know what action resolves the block.
We live and work in systems with constraints. These constraints don’t make design or marketing less powerful—they refine it. When you accept the message for what it is, you open up the opportunity to educate the user elsewhere. The time to empathize and persuade is before the error, not inside the error response object.
Educate Where It Counts
Instead of rewriting this kind of message, redirect that creative energy where it belongs: improving documentation, onboarding content, or alert threshold messaging inside the app—before failure occurs. Prompt the user with:
- “Your current usage rate is approaching your balance limit.”
- “Transactions over €50 may be declined unless you top up.”
- “Click here to review or upgrade your plan.”
That is where persuasion belongs. That is where narrative meets necessity. That is how Marketing and Product can dance without stepping on each other’s toes.
Respect the Message Boundary
So here’s the simple takeaway: JSON responses aren’t blank canvases for storytelling. They’re industrial signals. Let them be the clearly marked road signs they were built to be. Respect their purpose and educate users outside the point of failure—not during it.
Would you want your car’s “Low Fuel” light to read like a haiku? Or do you just want to know it’s time to find a petrol station before you’re stuck on the Autobahn?
#SystemDesign #UXWriting #ErrorMessaging #TechnicalContent #SaaSProduct #MarketingBoundaries #ClarityOverCreativity #IncludeDon’tInflate
Featured Image courtesy of Unsplash and Ilya Semenov (6uFROinaC3g)
