Health Check
GET /api/health: what it answers, how to point an uptime monitor at it, and why it needs Hyperdrive's query cache off.
GET /api/health tells you whether the Worker runs, whether it reaches the database, and which version answered.
{ "status": "ok", "version": "74e6e015-ef48-4f69-bdb7-997ba6e1097f" }| Answer | Means |
|---|---|
200 { "status": "ok", "version": … } | The Worker answered and the database replied within 2 seconds |
503 { "status": "error" } | The database did not reply. No version, no detail: the route is public |
429 | Too many requests: 60 a minute per visitor, 600 a minute for everyone, per Cloudflare location |
version is the Worker version that served the request, so during a gradual rollout two requests can differ. Locally and in previews it is dev. Nothing is cached.
Point a Monitor at It
- Use the exact path
/api/health:/api/health/is not found. - Check the status code and, if the tool can,
"status":"ok". - Alert on two or three failures in a row, not one: a single slow database reply is a
503. - Treat
429as unknown, not down. A flood can use up the shared limit and make a healthy site answer429to your monitor.
Why It Works While the Database Is Down
The route does not read a session. The session middleware asks the database on every request that carries a cookie, so a route behind it would answer 500 exactly when you need 503. apps/web/lib/sessionless-paths.ts lists the paths middleware/06.session.ts skips (SESSIONLESS_PATHS: /api/health and /api/client-errors). Exact paths only: add another public route that must work during an outage to that list, never a prefix.
Hyperdrive's Query Cache
The check runs select now(), which Hyperdrive never caches. Your own reads are cached for up to 60 seconds unless you turned the query cache off after the first deploy, as Production Deploys says. A cached read would also let a removed member keep access. See CPU Time and Database.
Check From Your Terminal
SITE_URL=https://your-site.com pnpm kit:doctor --prodIt reads /api/health and says what to do for a 503, 429, a redirect, a 404 (deploy the latest code) or any other answer. It never prints the body and never follows a redirect. SITE_URL here is the address to check, in your own terminal. Use the one your site really answers on: the check reports a redirect instead of following it.