The standard health check is four lines and returns 200 OK unconditionally. It answers one question: is the HTTP server accepting connections? That question was rarely the interesting one, and the endpoint will keep saying everything is fine while your database is unreachable, your queue is stalled, and every real request returns 500.
The other direction is worse. A health check that verifies every dependency turns a slow third-party API into a full outage, because your platform kills healthy instances for failing a check about something they do not control. Both mistakes are common and they have the same root cause: one endpoint doing two different jobs.
There are two checks, and they answer different questions
Kubernetes named these clearly enough that the vocabulary is worth borrowing even if you never touch Kubernetes.
- Liveness — Is this process wedged? A failure means restart me. It must not depend on anything external, because restarting your process cannot fix someone else's database.
- Readiness — Should this instance receive traffic right now? A failure means take me out of rotation. It may depend on things this instance needs to serve a request, and it is allowed to fail temporarily without anything being killed.
The single most valuable change most teams can make is splitting these apart. One endpoint that both restarts you and de-registers you cannot be tuned, because every threshold that makes it a good liveness check makes it a bad readiness check.
Liveness: almost nothing
A good liveness check verifies that the process can still do work, and nothing else. If your event loop is blocked, if a deadlock has your worker pool stuck, if memory pressure has made the process useless, this should notice. If a third-party API is down, this should not care.
// Liveness. No dependencies. The only failure mode it detects is
// "this process is no longer able to serve anything".
let lastTick = Date.now();
setInterval(() => { lastTick = Date.now(); }, 1_000).unref();
app.get("/livez", (_req, res) => {
// If the event loop has been blocked for 30s, we are wedged.
if (Date.now() - lastTick > 30_000) return res.status(503).send("stalled");
res.status(200).send("ok");
});For many applications the honest liveness check really is a bare 200. That is fine. The point is that it is deliberately bare rather than accidentally bare.
Readiness: what this instance needs to serve one request
Readiness checks the things without which this instance cannot do its job. The test for including a dependency is simple: if it is down, would every request to this instance fail? If yes, include it. If some requests would still work, leave it out and let those requests fail on their own.
A database your app cannot function without qualifies. A recommendations service that degrades to a default list does not. A cache does not, unless you cannot serve without it, in which case it is not a cache.
app.get("/readyz", async (_req, res) => {
if (shuttingDown) return res.status(503).json({ status: "draining" });
try {
// Cheap, and with a timeout shorter than the probe's own timeout.
await withTimeout(db.query("select 1"), 2_000);
} catch (err) {
return res.status(503).json({ status: "db_unavailable" });
}
res.status(200).json({ status: "ok" });
});
// select 1 -- not a count, not a join, not a query that touches user
// tables. You are checking that a pooled connection works, not
// benchmarking the database on a five-second interval forever.Startup is a third case, and it is why deploys fail
An app that takes 45 seconds to become ready — JIT warm-up, a large in-memory index, migrations, connection pools — will fail a readiness probe that starts checking after five seconds with three retries. The platform concludes the deploy is broken and rolls back, and the logs show a perfectly healthy application starting normally.
Two fixes, and you want both. Use a startup probe if your platform has one, which gives a generous window before the normal readiness schedule takes over. And where you cannot, set the initial delay to cover your realistic worst-case boot rather than your average.
Worth stating plainly: if you cannot work out why a deploy fails while the app appears fine, this is the first thing to check. It is by a wide margin the most common cause.
Health checks are half of graceful shutdown
The other place health checks earn their keep is deploys. When your instance receives SIGTERM, it should immediately start failing readiness while continuing to serve in-flight requests. That ordering is what makes a deploy invisible to users.
The reason is that load balancers learn about your state on a delay. If you stop accepting connections the instant SIGTERM arrives, requests already routed to you are cut, and users see a handful of 502s that nobody can reproduce afterwards.
let shuttingDown = false;
process.on("SIGTERM", async () => {
shuttingDown = true; // /readyz now returns 503
// Give the load balancer time to notice before refusing connections.
// This should exceed (probe interval x failure threshold).
await sleep(10_000);
server.close(async () => { // finish in-flight requests
await db.end();
process.exit(0);
});
});
// Without the sleep, in-flight requests are cut and you get a small
// spike of 502s on every deploy that nobody can explain later.The mistakes worth naming
- One endpoint for both jobs. Restart-me and remove-me-from-rotation cannot share a threshold. Split them.
- Checking dependencies in liveness. Turns a dependency blip into a fleet-wide restart and a thundering herd.
- Expensive checks. A probe running every five seconds across twenty instances is a lot of queries. Keep it to select 1, and cache the result briefly if you must check something costly.
- Checking things you do not need. Every dependency in a readiness check is a new way for your app to be marked down for something it can survive.
- No timeouts on the checks themselves. A hanging dependency should produce a fast, specific failure, not a probe timeout with no detail.
- Binding the health endpoint to localhost. It works locally and the platform's probe can never reach it, which produces a deploy failure with entirely healthy logs.
- Returning 200 with a body saying "degraded". Nothing reads the body. The status code is the entire interface.
A third endpoint, for humans
The status code is all a probe understands, but people debugging at three in the morning want more. A separate detailed endpoint — behind authentication, since it describes your internals — is a good place for it.
GET /internal/health (authenticated; not used by any probe)
{
"version": "1.24.0",
"commit": "a3f91c2",
"uptime_seconds": 84213,
"checks": {
"database": { "ok": true, "latency_ms": 3 },
"cache": { "ok": true, "latency_ms": 1 },
"queue": { "ok": false, "error": "connection refused", "since": "2026-08-25T09:14:02Z" }
}
}Note that the queue being down does not make this endpoint return 503, because it is not what readiness is for. It is information for a human, not a signal for a scheduler — and keeping those two things separate is the whole idea.
Wrapping up
Split liveness from readiness. Keep liveness free of anything external. Put in readiness only what this instance genuinely needs to serve a request, with a timeout on each check. Give slow-starting apps a startup window. Fail readiness on SIGTERM before you stop accepting connections.
That is maybe forty lines of code, and it converts your health endpoint from a formality into the thing that makes deploys invisible and outages short.