diff --git a/src/__tests__/not-found-handler.test.ts b/src/__tests__/not-found-handler.test.ts
new file mode 100644
index 0000000..49037b8
--- /dev/null
+++ b/src/__tests__/not-found-handler.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import supertest from "supertest";
+import { app } from "../index.js";
+
+describe("404 handler", () => {
+  describe("API paths return JSON", () => {
+    it("returns JSON 404 for /v1/ paths", async () => {
+      const res = await supertest(app).get("/v1/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ error: "Not Found: GET /v1/nonexistent" });
+    });
+
+    it("returns JSON 404 for /api paths", async () => {
+      const res = await supertest(app).get("/api/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ error: "Not Found: GET /api/nonexistent" });
+    });
+
+    it("returns JSON 404 for /health paths", async () => {
+      const res = await supertest(app).get("/health/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ error: "Not Found: GET /health/nonexistent" });
+    });
+  });
+
+  describe("Browser paths return HTML", () => {
+    it("returns HTML 404 with correct status", async () => {
+      const res = await supertest(app).get("/nonexistent-page");
+      expect(res.status).toBe(404);
+      expect(res.headers["content-type"]).toMatch(/html/);
+      expect(res.text).toContain("404");
+      expect(res.text).toContain("Page Not Found");
+    });
+
+    it("HTML 404 includes navigation links", async () => {
+      const res = await supertest(app).get("/some/random/path");
+      expect(res.status).toBe(404);
+      expect(res.text).toContain('href="/"');
+      expect(res.text).toContain('href="/docs"');
+    });
+  });
+
+  describe("Different HTTP methods", () => {
+    it("handles POST on non-existent API route", async () => {
+      const res = await supertest(app).post("/v1/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ error: "Not Found: POST /v1/nonexistent" });
+    });
+
+    it("handles PUT on non-existent API route", async () => {
+      const res = await supertest(app).put("/v1/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ error: "Not Found: PUT /v1/nonexistent" });
+    });
+
+    it("handles DELETE on non-existent browser route", async () => {
+      const res = await supertest(app).delete("/nonexistent");
+      expect(res.status).toBe(404);
+      expect(res.text).toContain("404");
+    });
+  });
+});