Summary: When facing a dry, technical response from software—like a JSON error message—it’s tempting to shrug it off as background noise. But doing so misses an excellent opportunity to clarify the relationship between systems, users, and the psychological expectations embedded in automated communications. Today, we break down the meaning, function, and human implications behind the typical error message that tells you your balance is too low to complete a task. This is not a story. It’s a prompt—one demanding we question assumptions about design, user experience, and communication clarity in technology.
What Looks Like Noise Might Be a Signal
At first glance, a JSON response like this seems inert. No characters, no arc, no tension—just key-value pairs in cold brackets:
{
"error_code": 402,
"name": "InsufficientBalance",
"status": "error",
"message": "Your account does not have enough credits to proceed.",
"readable_message": "Please recharge your account to run this request."
}
This isn’t storytelling. It’s status reporting. The message informs us of a broken transaction. A request was made. The backend system checked the user’s account. It found the balance depleted. The system refused to fulfill the request and instead returned this structured rejection.
What’s Actually Being Communicated?
Let’s zoom out. While the message feels mechanical, it embeds more than technical facts. It reveals the business logic of the platform and assumptions about user behavior. You could read this five-item message as a compressed version of a longer dialogue:
- You tried to do something.
- The system asked: do you have enough money?
- The answer was No.
- The system denied the request.
- You are instructed to pay up if you want service to continue.
In technical language, it’s precise. It states the cause and prescribes what the human should do next. But it also shows how human-unfriendly such interactions can be. What’s the emotional message here? “Rejected.” “Not enough.” “Go pay.” If we pause, we sense the cold efficiency here might be costing more than it saves. How does your client respond to a message like this? What tone do they perceive? What emotion does it evoke?
Error Reporting Is Brand Messaging
No one clicks a button planning for failure. Yet, that’s exactly when platforms choose to speak to them. These error messages carry more weight than you think—they form a user’s perception of reliability, compassion, and even professionalism. Whether it’s a Just-in-Time prompt or a database timeout, these failures expose the company’s hand. They show how much—or how little—empathy you have built into your process.
This is where many firms fail. An error message that says “InsufficientBalance” is informative to a developer but alienating to a customer. It mimics the rigidity of systems, not the flexibility of real conversations. Here’s a test: If your platform spoke like a person, would you keep the same phrasing?
What Could Make These Messages Work Better?
There’s nothing wrong with structure. JSON is a format meant for machines. But even machines serve humans. The problem arises when we forget the recipient during the design phase. Developers think “Readable_Message” is enough. Is it? Whose definition of “readable” are we using?
Let’s apply a few principles:
- Reciprocity: Add value before demanding action. Instead of “Recharge your account,” try “You’re just 5 credits short. Want to top up quickly?”
- Consistency: Match system messages to the tone used in onboarding and success screens. Don’t turn robotic only when things go wrong.
- Social Proof: Show reassurance. “Most users top up via PayPal and continue instantly.”
- Authority with Empathy: “Our system paused your request until your balance is positive. This protects both your data and resources. You’re in control.”
None of these add complexity. In fact, they remove friction. They reduce mental distance between user and platform—which pays long-term dividends in user trust.
Why This Still Isn’t a Story—and That’s Okay
There’s a temptation, especially in marketing, to try and turn everything into a story. That’s bad advice here. This JSON object is not a story—it’s an output, a symptom of logic rules firing in a controlled environment. But rational truth doesn’t mean you miss emotional truth. The story isn’t in the message—it’s in how the message lands. How will the user interpret it? What will they feel? What will they remember?
Sometimes, we must stick with dry facts because clarity matters more than persuasion. But in those rare cases where users hit an error, the tone, clarity, and helpfulness must rise—not fall. Problems are where trust builds fastest, or breaks entirely.
What Can We Learn from This?
Ask yourself: What tone do your platform’s failure messages carry? Do they sound like legal disclaimers or helpful colleagues? Are you only friendly when users are paying or winning—and silent or indifferent when things go wrong?
Using Chris Voss’ framework, we’d treat the user’s refusal to pay not as defiance but as lack of clarity or urgency. You don’t fix that with commands. You fix it with curiosity. Use open-ended framing: “What would happen if you don’t recharge today?” Mirror their concern: “Not enough balance, right?” Let them say “No” safely. That “No” is a pivot point—it means they’re still part of the conversation.
Designing Better Communication in Systems
If your platform handles transactions, credits, or quotas, every interaction—especially failures—becomes marketing. You’re showing your colors at the worst moment. Is your system defensive and sharp? Or calm, helpful, professional?
Even those silent JSON lines represent your company. That’s not fluff. It’s the skeleton of client experience. And it’s where smart companies do their best work—where no one’s watching, but people are listening.
#UXDesign #APIErrors #ClientCommunication #ProductDesign #HumanCenteredTech #BehavioralEconomics #IEEOMarketing
Featured Image courtesy of Unsplash and Markus Spiske (bMvuh0YQQ68)
