Read more notes

← All journals
August 19, 2026

'School Not Found' — a lie told by two honest components

Mid-afternoon, I click a link I have used all day — /bot-t627-academy/en/apply/start — and the page says “School not found.” The school exists. The database is fine. The API is up. Every component involved was doing exactly what it was built to do, and the composite told a user a flat lie about reality.

The anatomy. Our public apply pages fetch the school’s branding on every load. That fetch sat behind the same rate limiter as our brute-force surfaces — 50 requests per IP per 15 minutes — because “public endpoint, rate limit it” is the reflex best practice. Meanwhile the frontend’s fetch wrapper did the other reflex best practice: try/catch, return null, render the not-found page. Day-long testing exhausted the IP’s bucket, the branding fetch started answering 429, the catch swallowed it, null meant “no such school,” and a real school vanished from the internet.

Here’s what turns this from dev-environment trivia into a production incident waiting on a calendar: in The Gambia, a school’s wifi is one NAT’d IP. Every parent in the compound, every teacher on break, every phone in the staff room — one bucket. Fifty page loads per fifteen minutes, shared across an entire school community, during admission season, on pages that make four or five API calls each. Call it a dozen families browsing before the whole school starts being told it doesn’t exist — by its own admission system, at peak intake, with each locked-out family becoming a front-desk queue the product was sold to shrink.

The naive code — both halves individually defensible:

router.get("/public", authRateLimiter, schoolController.getPublicProfile);
export async function fetchPublicSchool(code: string) {
  try {
    return await apiFetch<ISchoolPublic>(`/tenants/${code}/school/public`);
  } catch {
    return null;
  }
}

The fix separates two things that should never have shared a word. First, reads and guesses get different buckets: brute-forceable surfaces (code resume, mint, step writes) keep the strict limiter that sizes our 8-digit code’s security math; harmless reads (branding, cycle facts, grade options) get a loose 600/15min bound that exists only to deter scraping. Second, only a 404 is allowed to mean “not found.” Everything else re-throws to an error boundary that says the true thing — try again, your progress is saved:

export async function fetchPublicSchool(code: string) {
  try {
    return await apiFetch<ISchoolPublic>(`/tenants/${code}/school/public`);
  } catch (err) {
    if (err instanceof ApiError && err.status === 404) return null;
    throw err;
  }
}

The transferable rule: a catch-all that maps every failure to one meaning is a translation layer that only tells one story, and under load it will be the wrong one. “Not found,” “not right now,” and “not for you” are three different sentences. The moment your error handling collapses them, some component elsewhere — a limiter, a deploy restart, a slow database — gains the power to make your UI assert things that are false. We didn’t find this by auditing error paths. We found it because the one person testing shared an IP with the test suite, which by accident simulated exactly what a school’s shared wifi will do for free on day one.

DESIGNER BLUEPRINT

A decision-tree diagram, top node “branding fetch fails.” Three branches, each ending in a distinct screen mock: (1) HTTP 404 → the existing “School not found” page with its check-the-address copy; (2) HTTP 429 / network / 5xx → the new error boundary screen: “Something went wrong — try again, your progress is saved,” with a retry button; (3) success → normal page. Overlay a “before” ghost in red showing all three branches collapsing into the “School not found” screen. Beside the tree, a small illustration of a school building with one router icon and many phones behind it, labeled “one IP = one bucket for everyone,” to make the NAT reality legible to non-engineers at a glance.