API Health Check Endpoints: Complete Implementation Guide

A health check endpoint is one of the most valuable additions to any production API. It gives load balancers, orchestrators, and monitoring tools a single URL to determine whether your service is ready to handle traffic — and exactly what's wrong when it isn't. This guide covers what to build, how to build it, and how to monitor it effectively.

What Is a Health Check Endpoint?

A health check endpoint is a dedicated URL — typically /health, /healthz, or /status — that reports the current operational state of your service. When called, it:

• Verifies the service process is running
• Checks connectivity to critical dependencies (database, cache, message queue)
• Reports overall service status as a simple pass/fail or detailed breakdown
• Returns an appropriate HTTP status code (200 for healthy, 503 for unhealthy)

Every component in your infrastructure uses this endpoint. Load balancers use it to decide whether to route traffic. Kubernetes uses it to decide whether to restart containers. Monitoring tools use it to trigger alerts. Your on-call engineer uses it to quickly assess an incident.

Liveness vs Readiness vs Startup Probes

Kubernetes distinguishes three types of health probes — and even outside Kubernetes, this mental model is useful for structuring your health checks:

Liveness Probe: /healthz/live

Answers: "Is this service alive, or is it stuck in a broken state that requires a restart?"

Liveness checks should be fast and simple — they just verify the process is running and not deadlocked. Don't include database checks here. If a database goes down, you don't want Kubernetes to restart your service — the service itself is fine, just a dependency is unavailable.

If the liveness probe fails, Kubernetes restarts the container.

Readiness Probe: /healthz/ready

Answers: "Is this service ready to accept incoming traffic right now?"

Readiness checks can be more comprehensive. Check database connectivity, cache availability, and any other dependencies required to serve requests. If the readiness probe fails, Kubernetes removes the pod from the service's endpoints — traffic stops routing to it — but doesn't restart it.

Use readiness probes to:

• Signal when a service has finished warming up (loading caches, establishing connection pools)
• Temporarily remove a pod from rotation when a dependency is unavailable
• Implement graceful shutdown (fail readiness before terminating)

Startup Probe: /healthz/startup

Answers: "Has the application finished initializing?"

Used for slow-starting containers. While the startup probe is active, liveness and readiness probes are disabled. Once it succeeds, Kubernetes switches to the liveness and readiness probes. Prevents slow startups from triggering liveness restarts.

What to Include in Your Health Check

A production-grade health check should validate your service's ability to do its job. For most services, that means:

Required Checks

• Database connectivity: Can you connect and run a lightweight query (e.g., SELECT 1)?
• Service process: Is the process running? Is memory usage within bounds?

Recommended Checks

• Cache connectivity: Is Redis/Memcached reachable?
• Message queue: Is Kafka/RabbitMQ/SQS reachable?
• Critical external API: Can you reach a payment processor or auth service?
• Disk space: Is there enough free disk space for logs and temporary files?

Optional Metadata

• Version: Current service version or git SHA (useful during deploys)
• Uptime: How long the process has been running
• Environment: Production, staging, etc.
• Check durations: How long each dependency check took

Health Check Response Format

The response body should be JSON with a consistent structure that monitoring tools and humans can parse:

Return HTTP 200 for healthy, HTTP 503 for unhealthy or degraded. This lets load balancers and proxies act on the status without parsing the body.

Implementation Examples

Node.js (Express)

Python (FastAPI)

Go

Health Check Timeouts

Health check endpoints must have strict timeouts. A health check that takes 30 seconds is worse than no health check — it blocks the load balancer from making routing decisions.

• Total health check timeout: 5 seconds maximum
• Per-check timeout: 2 seconds per dependency check
• Database check timeout: 1 second — if the DB takes more than 1 second to respond to SELECT 1, it's effectively unavailable

Run dependency checks in parallel when possible to keep total health check time low:

Security Considerations

What to Expose Publicly vs Privately

Not all health check details should be publicly accessible. Consider two tiers:

• Public /health: Returns only { "status": "ok" } or HTTP 200/503. No dependency details. Safe for load balancers and CDN health probes.
• Internal /health/detailed: Returns full component status, versions, and dependency states. Requires authentication or IP allowlist (internal network only).

Don't Leak Internal Details

Error messages in health check responses can reveal your infrastructure topology. "connection refused: host postgres-primary.internal:5432" tells attackers what database you're using and your internal hostname. In public health endpoints, return generic error messages like "database unavailable" rather than the raw exception.

Rate Limit Health Endpoints

Health endpoints that run database queries on every call can be exploited for denial-of-service attacks. Add rate limiting (100 req/min is generous for legitimate monitors) and cache health check results for 5-10 seconds to avoid hammering your database with health check queries.

Kubernetes Configuration

Here's a complete Kubernetes probe configuration using separate liveness and readiness endpoints:

Key settings:

• initialDelaySeconds: Wait before first probe (allows app to start)
• periodSeconds: How often to probe
• failureThreshold: How many consecutive failures before action
• timeoutSeconds: How long to wait for a probe response

Monitoring Health Endpoints from Outside

Health endpoints are most valuable when monitored continuously by an external system — not just your infrastructure. External monitoring catches issues your internal probes miss (network routing problems, CDN failures, geographic outages).

What to Monitor

• Availability: Is the health endpoint returning 200?
• Response time: Is the endpoint responding quickly? Slow health checks often precede full failures.
• Component status: Parse the JSON to alert on individual dependency failures
• Version changes: Track version field to verify successful deployments

Polling Frequency

Poll your health endpoint every 30-60 seconds from external monitors. This gives you a median time-to-detect of 15-30 seconds for outages, which is sufficient for most SLOs. Polling more frequently (every 10 seconds) is appropriate for high-availability systems, but generates more load.

For critical paths, set up monitoring from multiple geographic regions to distinguish regional outages from global ones.

Health Checks During Deployment

Health checks are critical during rolling deployments. The pattern:

1. Start new pod: Startup probe runs until it passes
2. Readiness probe passes: Pod is added to load balancer rotation
3. Traffic shifts gradually: Old pod gets less traffic as new pod handles more
4. Graceful shutdown begins on old pod: Readiness probe is deliberately failed to drain traffic
5. Old pod terminates: After all in-flight requests complete

To implement graceful shutdown, listen for SIGTERM and immediately fail your readiness probe while continuing to handle in-flight requests:

Common Health Check Mistakes

Checking Too Much

A health check that calls external payment APIs or runs complex queries makes your service dependent on those external systems for basic availability. If Stripe is down, should Kubernetes restart your containers? Probably not. Keep health checks focused on what's required to serve requests.

No Timeouts

Health checks without timeouts can hang indefinitely when dependencies are slow, causing the health check to appear failed and triggering unnecessary restarts or routing changes. Always set explicit timeouts.

Exposing Too Much Information

Detailed health responses on public endpoints leak infrastructure details. Use tiered endpoints: simple public check, detailed internal check.

Same Endpoint for Liveness and Readiness

Using the same endpoint for both means a database outage (which should only fail readiness) will also fail liveness — causing your pods to restart in a loop even though the application itself is fine. Always separate them.

Health Check Implementation Checklist

• ☐ /health returns 200/503 with JSON status body
• ☐ Separate /healthz/live and /healthz/ready endpoints
• ☐ Database connectivity check with 1-2 second timeout
• ☐ Cache connectivity check (if used)
• ☐ Checks run in parallel, not sequentially
• ☐ Total health check timeout < 5 seconds
• ☐ Results cached for 5-10 seconds to prevent DB hammering
• ☐ Sensitive details require authentication or internal network only
• ☐ Version/build info included for deployment verification
• ☐ Graceful shutdown fails readiness probe before terminating
• ☐ External monitoring polling the endpoint every 30-60 seconds
• ☐ Alerts configured for 503 responses and slow response times

Key Takeaways

• Health check endpoints are the foundation of reliable deployments and infrastructure automation
• Separate liveness (is the process alive?) from readiness (can it serve traffic?)
• Check only what's required to serve requests — external dependencies included
• Run checks in parallel with strict timeouts (2 seconds per check, 5 seconds total)
• Return 200 for healthy, 503 for unhealthy — not 500
• Cache health check results to avoid hammering your database
• Use tiered endpoints: simple public check, detailed internal check
• Monitor from external systems — internal probes alone don't catch network routing failures

A well-implemented health check endpoint is invisible when everything is working — and invaluable when something breaks. It's the first thing your monitoring tool checks, the first thing your load balancer consults, and the first thing an on-call engineer looks at during an incident. Get it right once and it pays dividends forever.