Summary: A plain JSON error message might seem like a digital dead-end to most people. But under its technical skin lies an important story about automation, failed assumptions, faulty user experience, and the widening chasm between system design and human understanding. This post breaks it all down—not to rewrite the message, but to expose the missed opportunity for clarity, context, and connection.
“Not a story” – But Whose Fault Is That?
If I hand you a receipt that just says “DECLINED,” that’s not much of a story either. You’d probably want to know: why? Was it over the limit? Expired card? Fraud alert? The same thing applies to software. The message mentioned—{"error": "Insufficient account balance"}—doesn’t tell a story, sure. But it fails because it doesn’t tell one. That’s the bigger point.
When users encounter messages like this, they’re not looking for code—they’re looking for consequences. They’re wondering: What does “insufficient” mean? How much more do I need? Has the system charged me already? What action do I need to take next?
So this isn’t just about API language. It’s about a fundamental failure of communication in digital systems—one that frustrates customers and burdens support teams. And ironically, it’s because developers or product owners often treat “Data” and “Story” as separate. They aren’t. Data becomes value only when it’s wrapped in meaning. That meaning is the story.
Why These System Messages Fail Humans
Naked error messages like this disconnect the user. They don’t prompt action, don’t give options, and worse—they put all the burden on the confused person to interpret what’s missing. And what happens then?
- They leave your platform.
- They open a chat or ticket that slows down your support funnel.
- They complain—on forums or worse, on reviews.
This is where Chris Voss’s principle of tactical empathy matters. People need to feel heard even by a website. If your system kicks back with a cold autopsy note—no explanation, no plan—it’s a dead end. You put your user in an emotional corner and expect a rational next step. That’s bad business. Think back to FBI negotiation logic: when emotions rise, logic falls. This applies here too.
The Remix: What Could Have Been Said
Now, no one expects your API to sing lullabies. But giving users a crisp, helpful message is low-cost and high-impact. So how would we rewrite that dead API message into something that moves action forward?
Let’s start with the structure:
- State the problem clearly: Not in developer-speak, but customer language.
- Explain the context: Was this during a payment attempt, subscription renewal, or API call cost?
- Offer the options: What should a human do now—add funds, contact support, or retry later?
- Use empowering language: Reinforce that this issue is fixable, and they’re not stuck.
Here’s a stronger rewrite that works in an app or web portal:
“Your account doesn’t have enough funds to complete this request. The current balance is $2.80, but the action you attempted needs at least $5.00. You can add funds now or contact support if this seems incorrect.”
Look at what this version does compared to the raw JSON:
- It frames the issue from the user’s perspective.
- It offers a choice, not just a rebuke.
- It opens the door to more conversation instead of halting it.
That’s what great communication does: it doesn’t stonewall, it invites.
The Cost of Neglecting This
Let me ask you this: how many users bail when your product sends them an unhelpful signal? Do you track that? Have you ever run heat maps or exit points on error pages? You should. Because every time someone hits an invisible wall built out of techy nonsense, you’re burning your own marketing dollars. Someone paid to get that user to your platform. A lazy error message just threw that money off a cliff.
And here’s the tricky part: most companies never know this is happening. Silence is the enemy in product feedback loops. The skimming, bouncing, quitting trouble is silent. But it stacks. And as Blair Warren reminds us—people will do anything for those who encourage their dreams… and nothing for those who dismiss their struggles. Your interface, your backend, your UX copy—all of that matters.
So Why Do Developers Still Do This?
Three reasons:
- They build for themselves, not the end user. It’s fast to surface the internal error message from a server. So they leave it as-is.
- No bridge between product and marketing teams. So the importance of tone, clarity, empathy, and user action never makes it into the sprint planning session.
- “It’s just an error.” No, it’s not. It’s the emotional turning point for your user. They either trust your product more—or abandon it. That’s high stakes.
What would it cost to fix these? Maybe ten minutes per error case. What would it gain you? Less confusion, fewer support calls, and more users who stick around because the product doesn’t make them feel stupid.
If You Build APIs Or Products, Ask Yourself:
- “What does this error sound like to someone who’s never coded?”
- “How would I explain this over the phone to my grandmother?”
- “What do I want the user to do next after seeing this?”
Stop dumping unsorted trash onto your users’ screens. They’re not there to interpret your server’s mood swings. They need clarity. They need context. And above all, they need direction.
The takeaway? If it doesn’t look like a story, maybe the storyteller gave up too soon. Every interface is a negotiation. Make sure your side isn’t silent when it matters most.
#UXFail #APIUX #SystemDesign #ProductMessaging #UserExperienceMatters #HumanCenteredDesign #TechCommunication #ErrorMessagesDoneRight
Featured Image courtesy of Unsplash and Egor Komarov (SEMtDLACmUk)
