Python Health Check Endpoints — Core Concepts

Design health check endpoints that give load balancers, Kubernetes, and monitoring tools the right signals about your Python app's status.

What Is a Health Check Endpoint?

A health check endpoint is a dedicated URL (typically /health or /healthz) that returns your application’s operational status. It responds with an HTTP 200 when healthy and a 503 when something is wrong.

Unlike regular endpoints, health checks exist for infrastructure — load balancers, orchestrators, and monitoring systems poll them automatically.

Types of Health Checks

Liveness Check

Answers: “Is the process alive and responding?”

A liveness check is minimal — it proves the app can accept HTTP requests. If this fails, the process should be restarted.

Return 200 with a simple response. Don’t check external dependencies here. If the database is down but the app process is alive, the liveness check should still pass.

Readiness Check

Answers: “Is the app ready to handle real traffic?”

A readiness check verifies that the app can actually serve requests. This includes checking database connectivity, cache availability, and any critical backing services.

If the readiness check fails, the load balancer or orchestrator removes the instance from the traffic pool but doesn’t restart it. The app might be warming up, running migrations, or waiting for a dependency to recover.

Startup Check

Answers: “Has the app finished initializing?”

Some apps take time to start — loading ML models, warming caches, running migrations. A startup check tells the orchestrator to wait before sending traffic. Once it passes, readiness and liveness checks take over.

What to Check

A good readiness check verifies critical dependencies without being too expensive:

Database — Run a simple query like SELECT 1
Cache (Redis/Memcached) — Send a PING command
Required external APIs — Only if they’re truly critical to every request
Disk space — If your app writes logs or temp files locally
Memory — Check if the process is approaching limits

Don’t check everything. If your app sends emails but can queue them for later, the email service isn’t a readiness dependency. Only check services that, if unavailable, would cause every request to fail.

Response Format

A minimal health response returns 200 or 503. A more useful response includes component status:

{
  "status": "healthy",
  "checks": {
    "database": {"status": "up", "latency_ms": 2},
    "redis": {"status": "up", "latency_ms": 1},
    "disk": {"status": "up", "free_gb": 42.5}
  },
  "version": "1.4.2",
  "uptime_seconds": 86400
}

When something fails:

{
  "status": "unhealthy",
  "checks": {
    "database": {"status": "down", "error": "connection refused"},
    "redis": {"status": "up", "latency_ms": 1}
  }
}

Including the version and uptime makes it easy to correlate health issues with recent deployments.

Kubernetes Integration

Kubernetes uses three probe types that map directly to health check types:

livenessProbe → Your liveness endpoint. Failure triggers a pod restart.
readinessProbe → Your readiness endpoint. Failure removes the pod from service endpoints.
startupProbe → Your startup endpoint. Failure during startup means Kubernetes hasn’t given up yet.

Configure probes with appropriate intervals and thresholds. A single failed check shouldn’t trigger a restart — use failureThreshold to require multiple consecutive failures.

Common Misconception

“Health checks should verify everything.” Over-checking makes your health endpoint fragile. If the health check hits five external APIs and one has a slow network, your app reports as unhealthy even though it can serve 95% of requests fine. Check only what would cause complete failure if unavailable.

The one thing to remember: Separate liveness from readiness — liveness means “the process runs,” readiness means “the process can serve traffic” — and only check dependencies that would break every request.

pythonwebdevops