Engineering
Why Health Checks Matter for AI-Built APIs
AI can generate an API quickly, but the platform still needs a truthful health endpoint before it should send production traffic.
The easiest health check always returns 200. The useful health check knows when an AI-built API should leave the route.
Separate alive from ready
Liveness asks whether the process is still running well enough to recover without a restart. Readiness asks whether it can safely serve traffic now. Combining both into one expensive endpoint can turn a slow dependency into a restart loop.
Keep the liveness path local and cheap. Let readiness cover the small set of dependencies that make the response path unusable when they fail. A background analytics service rarely belongs there; a required database connection often does.
- —Liveness: event loop or process is responsive; no external calls required.
- —Readiness: required request-path dependencies respond within a fixed deadline.
- —Startup: initialization and migrations are complete before readiness turns green.
Make failure bounded
A probe that waits indefinitely is not a probe. Set a short timeout, avoid unbounded retries inside the handler, and return a clear failure when the application cannot establish readiness in time. The platform can then stop routing new traffic while the process recovers or a replacement starts.
The endpoint should also avoid changing data. Health checks run often, from more than one place, and during already-degraded conditions. A read-only query or lightweight dependency ping is safer than a write used only to prove access.
export async function GET() {
const ready = await dependenciesReady({ timeoutMs: 500 });
return Response.json(
{ status: ready ? "ready" : "not_ready" },
{ status: ready ? 200 : 503 },
);
}Test the unhappy path
A health route that has only been tested while every dependency is up is unfinished. Stop the database, exhaust a connection pool, make a required upstream time out, and confirm that readiness fails before normal requests pile up.
Then restore the dependency and verify that the process returns to the route without manual intervention. The recovery path is part of the contract too.
- —Block database connections and verify readiness becomes 503.
- —Delay a required upstream beyond the probe deadline.
- —Send SIGTERM and confirm readiness fails before shutdown begins.
- —Restore dependencies and confirm the replica re-enters rotation once stable.
Avoid probe-driven incidents
Probe frequency multiplies quickly across replicas and monitoring locations. Ten replicas checked every second can add hundreds of dependency queries per minute. Keep the query cheap, cache only when the cache cannot hide a real outage, and add jitter if every replica would otherwise probe at the same instant.
Alert on sustained readiness loss and on the number of healthy replicas, not every individual failed check. One transient timeout is evidence; a shrinking serving pool is an incident.