Summary: This post addresses a widespread pain point in software systems that deal with transactions—receiving a cold, robotic error message when attempting an action without sufficient funds. The message referenced, an “InsufficientBalanceError” JSON payload, is clear but emotionally distant. It stops the transaction, but it doesn’t resolve the customer frustration. If what you’re building involves wallets, credits, or pay-to-play user actions, you cannot afford to treat this message as just another log line. It’s your first intervention opportunity to turn confusion into clarity, and a “No” into a longer conversation. This post breaks down what’s missing and how to fix it.
Why This Error Message Fails the Conversation Test
The JSON payload reads:
{
"error": "InsufficientBalanceError",
"message": "Your balance is too low. Please recharge your account."
}
Sure, it identifies the problem. The user doesn’t have enough balance. The next action is implied: add more money. But remember this—decisions are emotional before they are logical. When a system sends a message like this, it ignores context and assumes the user already knows:
- What their balance previously was
- Why the charge happened now
- How much more they need to complete the action
- How and where to recharge
You see the flaw? The message delivers facts and skips the story. It gives no direction, no emotional connection, and no clarity for what just happened. That’s not user-centric design. That’s bureaucracy hiding behind raw JSON.
Why Clarity Must Come Before Action
Before anyone recharges anything, they need to understand what went wrong (mirroring their silent question—“Why did this fail now?”). Without that, you’ve just told them a flat “No.” And here’s the linchpin: A “No” can trigger a deeper engagement, but only if handled with empathy and follow-up.
What would a better error message do?
- Validate the customer’s confusion: “Looks like you tried to [action], but your balance isn’t quite there.”
- Clarify requirements: “This action requires €4.00, and your current balance is €1.75.”
- Suggest next steps with specific links: “You can recharge here.”
- Anticipate objections with alternatives: “Not ready to recharge? Try switching to a lower-tier option.”
Now you’re talking to a human being, not pushing JSON errors into a void.
Treating Error Messaging Like Frontline UX
This isn’t just about wording—it’s about first impressions. Your error messages are a form of microcopy. Treat them as seriously as homepage headlines. This is where Cialdini’s principle of Reciprocity comes into play: Give your users clarity, empathy, and direction when things go wrong, and they’ll give you trust and time.
Let me ask you something: When was the last time an app told you “no” and made you feel good about it? Probably never. But that’s the point—if you can pull that off just once, you’re ahead of the pack.
Design Patterns to Improve the Dialogue
To improve user interaction in these moments, apply these 5 design tactics:
- Make the message transparent: Show current balance, required amount, and explain which transaction triggered the error.
- Use plain speech: Ditch developer lingo like “InsufficientBalanceError.” Use terms like “Not enough funds to continue.”
- Use open-ended prompts: Rather than forcing a single next step, ask: “Would you like to recharge now or explore lower-cost options?”
- Use mirroring in UI: Echo the user’s mental model; if they clicked ‘Send,’ echo that intent: “You tried to send credits to John…”
- Introduce strategic silence: Build in paused animations, delay modals, or behavioral cues that simulate how a person might react in real life—a slight pause before showing the retry link gives emotional breathing room.
What Happens if You Don’t Fix This
Ignoring the grip this error message has on transactional churn is playing with fire. If a user feels punished without explanation, they disengage. It confirms their suspicion that your product is either cheap, careless, or indifferent—none of which supports long-term growth.
People don’t leave your product because of errors. They leave because of how you respond to errors.
Frustration is a Communication Gap—Not a Feature Request
Every support ticket logged because of this error is a failure in messaging, not engineering. People aren’t asking for your architecture doc—they’re asking for someone to tell them where they stand, what they can do, and why things unravelled.
You don’t need to “educate the user” with documentation; you need to communicate with empathy. That’s how Blair Warren would put it—speak to their struggle, not your stack trace. Confirm their suspicions that tech often leaves them stranded and use that as your crack in the wall to offer clarity and trust.
The Rewrite That Opens the Door to Conversions
Let’s fix it. Here’s a better alternative:
{
"error": "BalanceTooLow",
"user_message": "You tried to send €4.00, but your account only has €1.75. No worries—we’ve saved your action. You can recharge your balance now or explore other options."
}
Plus, offer two buttons below:
- Recharge Now (link to payment)
- See Other Plans (link to cheaper options)
Notice the tone: Non-judgmental, helpful, and precise. No tech jargon. This isn’t about babying the user—it’s about respecting them enough to explain the situation clearly.
Now Ask Yourself: Where Else Are You Saying “No” Without Direction?
If this message appears anywhere in your system, you’ve got a friction point that can be turned into a growth moment. Do you know how often it triggers? Have you ever run heatmaps or screen recordings on drop-off at the payment prompt?
Are your errors giving up the conversation too early?
Good error messages keep people in the room.
Great ones turn obstacles into opportunities—and visitors into long-term users who feel heard and helped even when the system says “No.”
#ErrorMessageDesign #UXWriting #ProductMessaging #UserExperience #ChrisVossTactics #CustomerFirst #SaaSConversion
Featured Image courtesy of Unsplash and Julien L (sLrw_Cx6u_I)
