DEV Community

Daniel Pertu
Daniel Pertu

Posted on

Our 8 API routes answer with 10 status codes we wrote and 3 we never typed, and the same licence failure is a 200 on one route and a 403 on another

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
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 });
}
Enter fullscreen mode Exit fullscreen mode

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 }
  );
}
Enter fullscreen mode Exit fullscreen mode

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 }
  );
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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."}
Enter fullscreen mode Exit fullscreen mode

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",
});
Enter fullscreen mode Exit fullscreen mode

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)