Notifio is a desktop app that watches rental search pages on your own machine and emails you when something new appears. The website sells it, the server sends the email, and between them sit eight API routes: checkout, upgrade, contact, download, notify, validate, and two webhooks.
I have counted the status codes those routes return before. That measurement was about the number in the header. This one is about the JSON underneath it, which turns out to be a different story, because a status code is read by machines and a response body is read by whoever wrote the client.
The census
$ find src/app/api -name route.ts | wc -l
8
$ cat $(find src/app/api -name route.ts) | wc -l
1084
Eight files, 1,084 lines, 64 return statements, 55 of which hand back JSON. Split by whether the body says it worked:
bodies with an `error` key 41
bodies without one 14
non-JSON success (302 redirect) 1
--
JSON responses 55
So failure outnumbers success three to one in the source, which is what a route surface should look like. The interesting half is the 14.
Five words for yes
Those 14 success bodies, grouped by their first key:
key count routes example
--------------------------------------------------------------------------
sent 5 /api/contact, /api/notify { sent: true }
received 4 /api/webhooks/stripe { received: true }
url 2 /api/checkout, .../upgrade { url: session.url }
valid 2 /api/validate { valid: true, plan: ... }
success 1 /api/webhooks/resend { success: true }
Five words for the same idea: sent, received, url, valid, success. None of them is wrong. Each one was the obvious word in the file it was typed into, and no two of those files were written in the same sitting. sent is what a mailer says. received is what a webhook endpoint says to Stripe. success is what a webhook endpoint says when you have forgotten that you already decided on a word for this.
And the ninth route, the download endpoint, has no success body at all. Its happy path is a 302 to a presigned URL that expires in sixty seconds, so the only route on the surface whose success a user actually sees is the one that never says anything.
One word for no
The other 41 are completely consistent:
return NextResponse.json({ error: "Invalid request body." }, { status: 400 });
return NextResponse.json({ error: "Too many requests." }, { status: 429 });
return NextResponse.json({ error: "Failed to send email." }, { status: 502 });
One key, error, always a string a human could read, on every failing path of every route. Forty-one out of forty-one. That asymmetry is the finding: the shape nobody planned is uniform, and the shape everybody thinks about is not.
Two routes put something next to error. /api/validate prefixes its failures with the answer to the question that was asked:
return NextResponse.json({ valid: false, error: "Too many requests." }, { status: 429 });
And the upgrade route attaches a price to one of its 409s, so the app can correct the figure it was showing. That one has its own post, because a response body that the client is required to use on the failure path is a design decision rather than an afterthought.
Who actually reads these
Here is the part I did not expect. I grepped every client of this surface: two browser components on the site, three modules in the desktop app, and two third-party senders.
key written by read by
-----------------------------------------------------------------
url 2 routes 2 clients PricingClient, createUpgradeUrl
valid 1 route 1 client entitlement.fetchFromServer
error 8 routes 3 clients both web forms + the app's upgrade call
sent 2 routes 0 clients
received 1 route 0 clients
success 1 route 0 clients
The pricing page reads two keys and ignores the rest:
const data = await res.json();
if (!res.ok) {
setError(data.error ?? "Something went wrong. Please try again.");
return;
}
window.location.href = data.url;
The contact form reads one:
const data = await res.json();
if (!res.ok) {
setErrorMsg(data.error ?? "Something went wrong.");
}
sent: true is right there in the response and the form has never looked at it. It branches on res.ok, which is the status code, which was already the contract.
The desktop app agrees. There are four call sites that post to /api/notify and not one of them parses the body on success:
if (!res.ok) {
const body = await res.text().catch(() => '');
log(`[notify] Reply email failed (${res.status}): ${body}`);
return;
}
Note res.text(), not res.json(). On the failure path the carefully structured { error } body is logged as an opaque string. Two of the other three call sites do not keep the response object at all.
received: true and success: true are read by Stripe and Resend respectively, in the sense that both providers only check whether the status was 2xx. The words are decoration on a decoration.
The field that travels two hops to nowhere
/api/validate returns four keys on success:
return NextResponse.json({
valid: true,
plan: "lifetime",
autoReply: license.autoReply,
upgradePrice: priceQuote(UPGRADE_PRICE_PENCE, currency),
});
The app parses all four, caches them to disk, and carries plan one hop further into the monitor's result type:
| { ok: true; plan?: string }
Then nothing. No screen in the app renders a plan name, because there is only one plan and the product does not have tiers. plan: "lifetime" is a string the server composes, the app stores, the type system carries, and no human has ever seen. It cost nothing to add and it is the cheapest kind of dead weight: a field that is true, typed, cached and pointless.
The one body that has to be a body
There is exactly one place on this surface where the JSON carries information the status code cannot, and it is { valid: false } at 200.
A licence that does not exist is not a server error and not a client error. The request was well formed, the answer is no. Returning 200 with valid: false says "I successfully determined that this is not a licence", which is the truth, and it is why the desktop app can tell "your licence is invalid" apart from "I could not reach the server":
if (res.status >= 500 || res.status === 408 || res.status === 429) return null;
return { valid: false, autoReply: false };
null means "no answer, keep using the cached one". The explicit valid: false means "answer received, it is a no". That distinction exists because it once did not: a rate limit response used to be recorded as an invalid licence, which switched a paid feature off for someone who had done nothing but open the app twice.
What I am changing, and what I am not
Not the five words. A shared { ok: true } envelope across eight routes would be tidier to look at and would improve nothing, because the three unread words are unread precisely because the status code already carries the signal. Renaming dead fields is work that produces no behaviour.
What is worth doing is the opposite of consolidation: delete plan from the validate response, and keep writing { error: string } on every failure path by hand, because that is the key three clients genuinely read and it is the one that reaches a user as a sentence. The response bodies that matter on this surface are the ones a person ends up reading on the pricing page or the help page. The rest are notes to the developer, and it is worth knowing which is which before you spend an afternoon unifying them.
If you want to see the client side of this, the app is on the download page, and the licence validation it does on launch is the one call in this whole census whose body is load bearing.
Top comments (0)