Summary: When confronted with system errors like an insufficient account balance, some users expect they can reconstruct a narrative or story around the message. But not every string of data is a story—and mistaking transactional machine data for a readable tale is where confusion creeps in. In this post, we pull apart a common misconception and explain why structured technical feedback, like a JSON error response, is not only devoid of narrative but specifically built to avoid it.
What We’re Actually Looking At
The raw material in question is a JSON object. That is, a piece of structured data used mainly in APIs to communicate machine-to-machine, or from server to client. Think of it as an electronic telegram that means, “Hey, we’ve got a situation—insufficient funds.” That’s it. JSON isn't programmed to entertain, frighten, or inspire. It's built for clarity and accuracy.
This kind of message might read something like this:
{
"error": {
"code": 402,
"message": "Insufficient account balance",
"details": {
"requiredBalance": 10.00,
"currentBalance": 3.25
}
}
}
So what do we do with this? Attempting to reconstruct a plot where none exists misunderstands the function of the communication itself. There’s no protagonist. No antagonist. Just a plain barrier to a transaction, logged for transparency and technical debugging.
Why This Isn’t a Narrative
Let’s be blunt—data structures like this aren't meant to be rewritten like a thriller. They exist solely to pass precise, machine-readable information back to the user interface or developer tools. The intent is utilitarian, not expressive.
Trying to manufacture a narrative from a JSON error message would be like reading an electric bill and attempting to reimagine it as a short story. You can do it—but why would you? Especially when clarity is more valuable than creativity in this context.
Understanding the Purpose of JSON Responses
These structured messages serve three goals:
- Diagnose: Help users or systems understand why a request failed.
- Debug: Allow developers to take corrective action—either in the system or with the user interface.
- Proceed: Inform the next steps—fund the account, cancel the transaction, or notify the user with a clear message.
Anyone who has worked with APIs knows the goal isn’t to narrate but to minimize ambiguity. Errors must be explicit, recoverable, and consistently formatted. This is the opposite of storytelling. It’s logistics.
So Why Do People Look for Stories Here?
Two reasons—both perfectly human. First, there’s a growing social habit of applying storytelling structures to everything. And for good reason: stories are persuasive and sticky. Second, people seek meaning—even in error messages. They want emotional direction where the system gives them none.
If you've ever wondered, “What does this mean for me?” after getting an error message, you're not alone. But the machine doesn’t care. Its job was to deliver a data packet. Yours is to interpret it responsibly, not with fantasy but with logic.
What Can Be Learned From The Mistake?
When someone suggests rewriting a JSON error like the one above into a story, we can take that as a prompt—not to actually write the story, but to pause and clarify the actual structure and business workflow.
The real question is: Why did this happen, and what needs to change in our system or workflow to avoid it? That’s far more productive than storytelling. It’s a change-oriented mindset which pushes for consistency in outcomes—not cleverness in messaging.
Closing the Gap Between Technical Clarity and Human Frustration
Of course, empathy plays a role. While the JSON format isn’t for casual consumers, the surface interface that users see should translate this into human-readable terms: “Your card was declined due to low balance. Please add funds.”
What we must avoid is assuming the error message itself should carry the burden of narrative. It shouldn’t. Let the system deliver clarity. Let the user interface carry empathy. Let the backend simply work.
In business and software alike, not everything needs to be turned into “content.” Especially not technical responses. The point isn't whether there's a story to be told—but whether it's the right time to tell one at all.
#JSONerror #MachineCommunication #UserExperienceDesign #APIsimplification #TechClarity #DataStructures #ErrorHandling #UXwriting #DeveloperTools #NoStoryJustLogic
Featured Image courtesy of Unsplash and Hoang Trinh (BT9n_neqq8E)