How to add a health check — the endpoint that says your app is alive

The app is deployed, the URL opens — looks alive. Then it quietly hangs overnight, and you find out in the morning from a user's message.
A health check is a URL like /healthz that answers "I'm running." Your host, orchestrator or an external pinger knocks on it. No answer — restart, or wake you up.
Building one takes fifteen minutes. But there's one mistake that turns a health check from insurance into the cause of an outage. Let's start there, then build it step by step.
The big mistake: a check that talks to the database
The logic feels airtight: "we're checking health, so let's check the database too — without it the app is useless anyway."
Here's what actually happens. The database stalls for ten seconds under load. The health check times out and returns an error — on every instance at once, since they all share that database. The orchestrator sees them all dead and restarts them together. They come back up, rush the database for connections at the same time — and finish it off.
The database blinked; the app went down completely. It killed itself with its own check.
This isn't theory: the Kubernetes docs warn outright that carelessly configured liveness probes lead to cascading failures where containers get restarted unnecessarily under load.
Hence the rule: the "am I alive" check must not depend on anything external.
Step 1. Build /healthz — it checks nothing
The first endpoint answers one question: is the process alive and able to handle a request? That's it. No trips to the database, cache or third-party APIs.
app.get('/healthz', (req, res) => {
res.status(200).json({ status: 'ok' })
})
It looks pointless — and that's exactly the point. If this URL doesn't answer, the process is hung, out of memory, or the event loop died. A restart genuinely helps there. If the database is down, a restart won't help and the app should be left alone.
Step 2. Build /ready — this one does check dependencies
The second endpoint answers a different question: can I serve users right now? Dependencies belong here.
app.get('/ready', async (req, res) => {
const checks = {}
try {
await db.query('SELECT 1')
checks.db = 'ok'
} catch {
checks.db = 'fail'
}
const healthy = Object.values(checks).every((v) => v === 'ok')
res.status(healthy ? 200 : 503).json({ status: healthy ? 'ok' : 'degraded', checks })
})
The distinction matters. A failing /healthz means "restart me." A failing /ready means "hold the traffic, I'll sort myself out." The second one causes no restarts, so no cascade.
Note the database check is SELECT 1, not a real table query. You're confirming the connection is alive, not exercising business logic.
Step 3. Put a timeout on every check
Without a timeout, your check hangs for exactly as long as the dependency hangs. A health check that answers in 30 seconds is useless — the pinger declared you dead long ago.
const withTimeout = (p, ms) =>
Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), ms))])
await withTimeout(db.query('SELECT 1'), 1000)
A second is enough. If the database can't answer in a second, it isn't healthy either way.
Step 4. Return the right status code
Pingers and orchestrators read the HTTP status code, not your text. Alive — 200. Not ready — 503 Service Unavailable.
Common mistake: returning 200 with a body of {"status":"error"}. You technically reported the problem — but nobody outside noticed, because 200 means "all good."
Step 5. Don't expose extras
It's tempting to put the build version, branch name, database connection string and service list into the health check. Remember that this URL is open to the whole internet and requires no auth.
Outward: status, nothing more. Details go either to a separate protected endpoint or into your logs.
Step 6. Add an outside watcher
The endpoint won't check itself. You need someone external: your host or deploy platform settings (nearly all of them have a health check path field), an external ping service, or a simple cron that hits the URL once a minute and messages you if the answer isn't 200.
Crucially, the watcher must live on a different machine. Otherwise the server goes down together with its watcher, and there's nobody left to warn you.
What you end up with
Two URLs and a minute of work:
$ curl -s -o /dev/null -w "%{http_code}\n" https://your-site/healthz
200
$ curl -s https://your-site/ready
{"status":"ok","checks":{"db":"ok"}}
Now a hung app restarts itself, and you hear about a downed database from an alert instead of a user. The logical next step is understanding why it went down — that's what observability and its three signals are for.
Why two endpoints instead of one?
Because they have different consequences. One asks for a restart, the other for a pause in traffic. Merge them and you get exactly the cascade from the top of this article: any external hiccup starts restarting your app.
What if I'm on plain hosting with no orchestrator?
/healthz is still useful: almost any deployment platform can ping a URL and restart the process. And if yours can't, an external pinger that simply tells you the site went quiet is plenty.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





