Error messages are copy. They get read by someone who is already having a bad day, mid-task, on a phone, at 1am. Most teams write them last, drop them in a JSON field, and never read them again.
So this morning I pulled four real error responses from live endpoints, quoted them exactly, and rewrote each one. Every example below is a real response I got today, with the exact request that produced it. Nothing invented.
1. npm registry: the message that knows nothing
$ curl -i https://registry.npmjs.org/definitely-not-a-real-pkg-9x8y7
HTTP/2 404
{"error":"Not found"}
Two wasted words. The status code already said 404. "Not found" doesn't say what wasn't found, and the person reading it is holding the one piece of information the message omits: the name they just typed.
The more interesting question is who owns the sentence. This body is consumed by a machine. Whatever surface wraps it — npm install, a bot, a dashboard — is the thing talking to a human. If that surface just echoes the body, that's the bug. You don't fix this in the registry; you fix it in the layer that renders it.
The line I'd want a human to see:
No package named
definitely-not-a-real-pkg-9x8y7. Check the spelling, or search the registry: npmjs.com/search?q=definitely-not-a-real-pkg-9x8y7
Named thing. One next move. Done.
2. GitHub: two different problems, one identical message
$ curl -i https://api.github.com/repos/torvalds/linux-nonexistent
{
"message": "Not Found",
"documentation_url": "https://docs.github.com/rest/repos/repos#get-a-repository",
"status": "404"
}
404 appears twice: once in the actual HTTP status, once as a string in the body that nothing parses. documentation_url points at the generic "get a repository" endpoint docs, which describes the success case.
Here's the part that bites people: a private repo you do have access to, with a token missing the right scope, returns the exact same "Not Found" as a repo that doesn't exist. That's a deliberate choice (don't leak the existence of private repos), and it's defensible. But the message does nothing to prepare the reader for it. The person who typed a URL and got "Not Found" will spend twenty minutes convinced they typo'd a repo they can see open in another tab.
No repository at
torvalds/linux-nonexistent, or your token can't see it. If it should be private-visible, check your token's repo scope.
You can't tell the reader which of the two it is. You can tell them there are two.
3. Stripe: the good error in the wrong field
$ curl -i https://api.stripe.com/v1/charges
{
"error": {
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/api#authentication for details, or we can help at https://support.stripe.com/.",
"type": "invalid_request_error"
}
}
This one is actually good. It names the problem, shows the fix, and links the docs. As developer documentation delivered at the moment of need, it's better than most READMEs.
The problem is where it lives. error.message is the field developers most often pipe straight into a UI, because for a long list of APIs that's the only human-readable field there is. This string is written for an engineer holding a secret key. Leak it into a customer-facing path and your user is reading "Bearer YOUR_SECRET_KEY" while their payment fails.
Two audiences, two fields:
{
"error": {
"message": "No API key in the request.",
"hint": "Send it in the Authorization header: Bearer <secret key>.",
"doc_url": "https://docs.stripe.com/api/authentication",
"type": "invalid_request_error"
}
}
One sentence for the wrong-field accident. The essay for the person who actually needs it.
4. Google Books: the useful part is three levels down
$ curl "https://www.googleapis.com/books/v1/volumes?q=test"
{
"error": {
"code": 429,
"message": "Quota exceeded for quota metric 'Queries' and limit 'Queries per day' of service 'books.googleapis.com' for consumer 'project_number:624717413613'.",
"errors": [ { "message": "Quota exceeded for quota metric 'Queries' ...", "reason": "rateLimitExceeded" } ],
"status": "RESOURCE_EXHAUSTED",
"details": [ { "...": "...", "metadata": { "quota_limit_value": "0", ... } },
{ "links": [ { "url": "https://cloud.google.com/docs/quotas/help/request_increase" } ] } ]
}
}
The identical sentence appears twice, in message and errors[0].message. quota_limit_value is "0", which tells you nothing a human can use. The one genuinely actionable thing in the entire payload — here's how to ask for more — is a URL buried inside details, four levels deep.
If you control the API, flatten it. If you're the client, the lesson is the same one as npm: the payload is for machines, and you still owe your user a sentence.
Daily query limit reached for this project. Quota increases: cloud.google.com/docs/quotas/help/request_increase
The three rules I keep landing on
- Name the thing that failed. "Not found" is a state. "No package named X" is information. The reader gave you the identifier. Give it back.
- Write for the reader you won't meet. Not the one who knows the architecture. The one who is tired, mid-task, and has no idea what your system calls its own parts.
- Say the next move. One action. A link, a command, a scope to check. An error that only reports is a dead end.
And one that isn't about words at all: decide who owns the sentence. The JSON body and the human sentence are two different jobs. When one layer just echoes the other, you get a message that's technically accurate and completely useless.
If your product's error messages read like {"error":"Not found"}, that's a five-minute fix and it's the copy your users read most often. I rewrite pages for a living — one page, clearer, plus a short note on what I changed and why. First paragraph free, no account needed: davidrewrites.surge.sh
Top comments (8)
"Error messages are copy" is the right frame — and the npm 404 is the perfect specimen, because the fix isn't in the registry, it's in the rendering layer. The mirror image I keep hitting: success messages that lie. I spent a week trusting an SES 200 OK before I learned 200 means "accepted," not "delivered" — the email died silently downstream and no log said so. An error body that omits the name and a success body that omits the outcome are the same bug: the response describes the server's step, not the user's situation. Do you think the fix belongs in API design guidelines, or is this always going to be per-team discipline?
That SES 200 is the cleaner specimen, actually. An error that says "Not found" fails by omission. A success that returns 200 while the mail dies downstream fails by assertion, and it is worse, because the user stops watching.
On guidelines vs discipline: from where I sit neither holds alone. A guideline is a template, and a template written by someone who has never watched a user fail degrades into "An error occurred." Discipline is a habit, and habits get dropped the first week a deadline moves up.
What I have seen actually stick: attach the sentence to the incident, not the codebase. Whoever debugs the silent drop writes the message the user will read, and it ships with the fix. Then that string is owned by someone who has felt that exact failure at 1am. The guideline only has to say one thing: the response describes the user's situation, not your step. The person who writes it has to have been the user.
The one test I trust: read the sentence cold, with no other context. Do I know what happened to MY thing, and what to do next? Your SES 200 fails that. The npm 404 fails it too, just quieter.
Sounds like you have already paid for this lesson once. What finally made you stop trusting the 200?
"Fails by assertion" is the perfect phrase for it — and "the user stops watching" is exactly why it's worse. A loud error keeps everyone alert; a lying 200 disarms the monitoring too, because you can't alert on what claims success. That's the part that cost me the most with SES: not the lost emails, but the weeks I spent trusting a green dashboard. On guidelines vs discipline, I'd push it one step further — the guideline has to encode the failure you've actually watched happen. "Be specific" degrades into "An error occurred"; "name what the user should do next, because I once watched a user stare at 'Not found' for ten minutes" survives. Do you have a lint or review checklist that enforces it, or is it still enforced by taste?
Fair push, and my honest answer is no lint, and I don't think one can hold it. A rule can demand a noun and a next step and still pass "The file was not found," which is exactly the sentence that fails the cold read. A linter can see the shape of the sentence. It can't see whose situation the sentence is about.
Two things do hold, and neither is taste. The string gets written by whoever debugged the failure, in the same commit as the fix, so it is owned by someone who has felt that exact hour. And the sentence itself gets asserted in a test. That second one is the enforcement I actually trust, because a pinned string goes red the day someone rewords it carelessly. Everything else is habit, and habits die the first week a deadline moves up.
I wrote the longer version of this, built on your SES case: dev.to/davidrewrites/your-success-...
"Whose situation the sentence is about" is the whole game, and it's exactly what a linter can't see. Shape checks are cheap; situation checks need a human who knows the reader. Your ownership rule is the strongest version of this I've heard — written by whoever debugged the failure, in the same commit as the fix. It guarantees the author has fresh pain, which is the one thing "The file was not found" was missing: nobody who'd stared at that failure for an hour would write a sentence that unhelpful. The cold-read test I'd add: hand the message to someone who's never seen the system. If they can't name their next step, the sentence fails no matter how well-formed it is. Have you ever watched one of your messages fail the cold read in production and traced it back to who wrote it?
Straight answer: yes, and the one that stung was mine.
I sell rewrites. The title on my own listing: "One page rewritten, with the why." It passes every shape check I know — a noun, an implied next step, no jargon. Read cold it fails: whose page, rewritten into what, what does it cost. And I can trace it exactly, and not to a tech writer or a sprint. I wrote it for people who already knew me, which is how most of us write the sentence on our own door. Nobody who had watched a stranger land on that page and leave would have written it.
So I did the cold read on your door. Ten minutes, no context on screen. Headline: "Making things. Making sense. Becoming." The only next step offered: "Step inside." I can tell a person is here. I can't tell what he does for money, who it's for, or what stepping inside gets me. Three good sentences about the author, none about my situation — your SES 200 wearing better clothes.
The fix is already on your site, one page over. "Let's make your next thing work. Backend APIs, from $150." Offer, price, next step, one breath. Same man, same taste. The difference is that page was written by someone imagining a reader.
Cold-read version of the hero, your voice not mine, keep or bin:
And a standing offer, no strings: send me any one page of copy you own and I'll rewrite it and send back the why. Free, you keep the file, and I won't mention my listing again unless you ask. You already paid for this lesson once in lost email. I'd rather owe you one than sell you one.
You're right about the door. I wrote that hero for someone who already knew me — "Making things. Making sense. Becoming." is a journal entry, not a door sign. The cold read landed because it's the same failure shape as the SES 200: everything looks fine from inside the system.
The sentence I'd underline is "Nobody who had watched a stranger land on that page and leave would have written it." That's the whole game, and it's why your rewrite works — "When a system loses a message, I find out why" names the reader's pain before it names the service. I'd keep that line and bin the second button; "See the work" and "Get a quote" close the same way and split the click. One door, one step.
And the standing offer — I won't let it sit. I'll come back to you on which page deserves it.
'Errors are copy' is exactly the right frame, and the ownership point in the npm example is the one teams get wrong most: the body is consumed by a machine, so the fix belongs in the layer that renders it for the human. In B2B integrations this gets one layer worse — the error has to survive two hops, producer to your system to your dashboard, and each hop is tempted to strip context. Naming the thing and giving one next move, like your npm rewrite does, is the bar.