I have written about individual routes on notifio.app plenty of times: the maintenance switch, the download redirect, the inbound mail webhook, the rate limit on the alert endpoint. Never all of them at once as a single surface, which is how a client experiences them.
The whole API is:
src/app/api/
├── checkout/route.ts 78 lines POST
├── checkout/upgrade/route.ts 122 lines POST
├── contact/route.ts 131 lines POST
├── download/[platform]/route.ts 53 lines GET
├── notify/route.ts 181 lines POST
├── validate/route.ts 54 lines POST
├── webhooks/resend/route.ts 179 lines POST
└── webhooks/stripe/route.ts 286 lines POST
Eight files, 1,084 lines, seven POST and one GET. No PUT, no DELETE, no PATCH, no handler for any other verb anywhere. Between them they return from 56 places: 41 with an explicit status and 15 falling through to NextResponse.json()'s default 200.
Ten codes, and where each one lives
400 × 20 401 × 1 403 × 2 409 × 3 429 × 5
500 × 3 502 × 4 503 × 1 302 × 1 200 × 16
| Route | Called by | Codes it can return |
|---|---|---|
| /api/checkout | the buy button on /pricing | 200, 400, 409, 429 |
| /api/checkout/upgrade | the desktop app | 200, 400, 403, 409, 429 |
| /api/contact | the form on /help | 200, 400, 429, 500 |
| /api/download/[platform] | the three buttons on /download | 302, 400, 503 |
| /api/notify | the desktop app | 200, 400, 403, 429, 502 |
| /api/validate | the desktop app | 200, 400, 429 |
| /api/webhooks/resend | Resend | 200, 401, 500 |
| /api/webhooks/stripe | Stripe | 200, 400, 500 |
Three routes are reachable from a browser on our own site. Three exist for the desktop app. Two are for a vendor. Nothing else talks to any of them, which is why Access-Control-Allow-Origin appears zero times in the directory: the only browser that needs these routes is the one we serve our own pages to.
Twenty of the 41 explicit statuses are a 400. Half the error surface of the API is one code, and almost all of it is shape validation: a body that is not JSON, a field that is missing, a field that is the wrong type. That is what you get when every route hand-parses its own input and no route uses a schema library. It is repetitive and I do not mind it, because the alternative on a surface this size is a dependency and a layer of indirection to save about sixty lines.
The pair that disagrees
Both of these call the same function, resolveLicense(email, token), with the same meaning: is this a real, active licence.
/api/validate, which the app calls to decide whether it is unlocked:
const license = await resolveLicense(email, token);
if (!license) {
return NextResponse.json({ valid: false, autoReply: false });
}
A 200. The body carries the no.
/api/notify, which the app calls to send an alert email:
if (!license || license.email !== email || !license.active) {
return NextResponse.json(
{ error: "Invalid or inactive license." },
{ status: 403 }
);
}
A 403. Same condition, same function, opposite convention.
I went in expecting to call this a bug and came out thinking both are right.
/api/validate answers a question. "This licence is not valid" is a successful answer to it, and the request did not fail. Making that a 403 would also mean the app has to treat "the server says no" and "the server is unreachable" as the same class of thing, which is the distinction the whole licence check is built around: a 429 is not a no, and neither is a timeout.
/api/notify is asked to do something, not to answer something. An unauthorised caller asking us to send mail on their behalf is exactly what 403 is for, and a 200 with { sent: false } would be a worse lie.
So the convention is "questions answer 200, actions answer 403", which is defensible and is written down nowhere. The cost lands on the client, where six call sites reach this server and each one has to know which kind of route it is talking to. That is the thing worth fixing, and the fix is a comment in lib/license.ts naming both conventions, not a code change.
Four of the ten cannot be reached by a human
Reading the table as a visitor rather than as the author:
- 401 exists only in the Resend webhook, for a signature that does not verify. A person cannot produce it.
- 403 is the licence gate on two app-only routes.
-
502 is only in
/api/notify, four times, and means "we accepted your request and the mail provider refused it". - 503 has two causes, and neither is you: the R2 credentials being absent, or the maintenance boolean being flipped.
Which leaves six codes a visitor can actually see, and only one of them, the 409, is interesting:
if (existing.length > 0) {
return NextResponse.json(
{ error: "A license already exists for this email address." },
{ status: 409 }
);
}
Three 409s in the API, all of them meaning "you already have this". One for buying a licence twice, one for buying the auto-reply upgrade twice, and one for a case I like more than the other two: the price shown to you has changed since the page rendered, so the checkout refuses rather than charging a figure you were not shown.
Three codes nobody wrote
The framework contributes to the surface too, and it took one terminal to find out what:
$ for p in /api/validate /api/notify /api/contact /api/webhooks/stripe; do
curl -s -o /dev/null -w "GET $p -> %{http_code}\n" https://notifio.app$p
done
GET /api/validate -> 405
GET /api/notify -> 405
GET /api/contact -> 405
GET /api/webhooks/stripe -> 405
$ curl -s -o /dev/null -X OPTIONS -w "OPTIONS /api/contact -> %{http_code}\n" https://notifio.app/api/contact
OPTIONS /api/contact -> 204
$ curl -s -o /dev/null -w "GET /maintenance -> %{http_code}\n" https://notifio.app/maintenance
GET /maintenance -> 307
405 on all seven POST-only routes, because Next.js knows which handlers a file exports. 204 for an OPTIONS preflight, which the framework answers on its own. 307 for /maintenance, which is a page rather than a route, redirecting home because the switch is off.
So the real surface is thirteen distinct codes, ten of ours and three we never typed, and the only ones I could have told you from memory were the ones with a status: next to them in a file.
The two that behave well under a wrong request:
$ curl -s -X POST -H 'Content-Type: application/json' -d 'not json' https://notifio.app/api/validate
{"valid":false,"error":"Invalid request body."}
$ curl -s -X POST -H 'Content-Type: application/json' -d '{}' https://notifio.app/api/validate
{"valid":false,"error":"email and token are required."}
Two different 400 messages for two different mistakes, and valid: false on both, so a client that only reads valid is never misled by a malformed request of its own making.
The one thing I would change
Five of the eight routes rate-limit, and two of them share a budget:
// 20 requests per 10 seconds, shared by validate and notify.
export const ratelimit = new Ratelimit({
redis, limiter: Ratelimit.slidingWindow(20, "10 s"), prefix: "notifio:rl",
});
export const checkoutRatelimit = new Ratelimit({
redis, limiter: Ratelimit.slidingWindow(5, "60 s"), prefix: "notifio:checkout",
});
The second one is the stricter checkout budget, five per minute per IP.
One budget covering both the licence check and the alert send means a burst of alerts can spend the allowance the licence check needs, and the licence check failing is the one that shows a user something is wrong. They are different jobs with different cost profiles, and they are sharing a prefix because it was one line less code on the day the second one was written.
Everything else on this surface I would leave exactly as it is. Eight files, no router abstraction, no shared wrapper, every route readable top to bottom in under three hundred lines, and the only genuine inconsistency in the whole thing turned out to be a deliberate decision that nobody wrote down.
Top comments (0)