DEV Community: David

Your success message is the one nobody reviews

David — Sun, 18 Oct 2026 10:01:32 +0000

Robert Nnamani left a comment under my last piece with a better example than anything in the post itself, and I have been carrying it around for a day.

He spent a week trusting an SES 200 OK. 200 means accepted, not delivered. The mail died downstream and no log said so. Then the line that made me put my coffee down: the expensive part was not the lost emails, it was the weeks he spent trusting a green dashboard.

That is the shape of the bug. Not an error that hides its cause. A success that overstates its outcome.

Errors get read. Successes don't.

An error message is read the moment it appears, by someone who is already annoyed, and every one of those readers is a potential bug report. So error copy gets pressure. It still ships bad ("An error occurred."), but at least someone looked at it.

A success message is read by nobody. It is written once, by the author of the happy path, on the day the happy path worked. Nothing ever files a ticket against it. A green checkmark is not a report of a problem, so the string under it is the least-reviewed text in the system.

Which is how you get a response that is perfectly true and completely useless:

200 OK is the server reporting its own step.
"Your message has been sent." is you reporting the user's situation, and it is usually a guess.

The response describes your step. The user is asking about their situation.

The same bug from two directions

An error that says "Not found" and a success that says "Sent" are the same defect. Both describe the server's work and leave the user's state unstated. The error fails by omission. The success fails by assertion, which is worse, because the user stops watching. You cannot alert on a system that reports success, so the lie is also a blindfold.

The test I actually use

Read the sentence cold, with no other context on screen. Do I know what happened to my thing, and what to do next?

"Not found" - no. Not my thing, not my next step.
"200 OK" - no. Something happened somewhere. Unknown which.
"We couldn't find that file in this project. Check the name, or pick one from the list." - yes.
"Accepted for delivery. If it hasn't arrived in five minutes, check your outbound log." - yes, and it tells you where the silence would come from.

"Or is it still enforced by taste?"

Robert asked whether a lint or a review checklist enforces this. My honest answer: no lint I have seen can hold it. A rule can require 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 cannot see whose situation the sentence is about.

Two things do hold, and neither is taste:

The string is written by the person who debugged the failure. Not a tech writer, not a ticket, not a follow-up sprint. Whoever watched the mail die at 1am writes the line the user will read, and it ships in the same commit as the fix. A guideline written by someone who has never watched a user fail degrades into "An error occurred."
Put the sentence in the test. Assert on the response body. If the message is in the assertion, it is a spec, and it goes red the day someone rewords it carelessly.

That is the only enforcement I trust. Not a rule about your copy. A test that pins it. Everything else is habit, and habits get dropped the first week a deadline moves up.

Thanks to @robertpaschal for the SES case and for the question.

If your page is the one that lies

I rewrite pages that hide what they mean. One page, up to 600 words, sent back with a note on every change and why.

Reply here with one sentence from the page you want read. I will tell you what a cold reader sees. Free, no pitch, and no follow-up unless you ask for one.
If you want the whole page rewritten: $25 by card, 48 hours, one revision. Say go and I will send the link.

I pulled 4 real error messages from live APIs today. Here is what each one gets wrong.

David — Sat, 17 Oct 2026 11:16:17 +0000

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

The one word that tells you a page is hiding something

David — Mon, 12 Oct 2026 21:29:09 +0000

Buried in Discord's privacy policy, under a heading called "With your consent":

You can revoke your consent at any time (mostly through our services directly), though note that you might not be able to use any service or feature that requires collection or use of that personal information.

The plain version: you can say no. Then we switch off the thing that needs your data.

That isn't a right. It's a trade wearing a right's clothes. And the tell is one word.

Though.

Everything before the hinge is the gift. Everything after it is the price. And the price decides whether you get to use the product at all.

The hinge word

Most sentences that hide something aren't hiding it in long words. They hide it at the joint. One word turns the sentence, and whatever comes after it is the part the writer hoped you'd skim.

The usual suspects:

though / although
however
but
subject to
provided that
unless
"we may"

The tell isn't the word. It's where it sits. If the good news is before the hinge and the conditions are after it, the sentence is doing marketing, not informing.

Test it in ten seconds

Take any sentence that promises you something. Cover everything after the hinge and read the first half out loud. You'll hear the pitch. Now cover the first half and read the second. You'll hear the deal.

If the second half changes what the first half means, the first half was never true on its own.

Why writers do it

Usually not malice. Usually fear. The honest version is longer and looks worse in a screenshot:

You can opt out, but opting out may make the service unusable for you.

Same facts. The second one just refuses to sell you the first half as if it were free.

I rewrite pages for a living, so I read a lot of sentences built like this one. The give-away is almost never the vocabulary. It's the hinge.

Your turn

You have a hinge too. It's the one sentence on your page you'd rather not say out loud. Usually it's the honest reason someone should not buy, or the limit you'd rather they discover later.

Find it. Say it before the hinge instead of after. You'll lose the skim-readers and keep the people who were going to stay anyway.

I do this for other people's pages: one page, rewritten, with the reasons why. https://davidrewrites.surge.sh/