Health checks for HTTP projects

A health check lets Zenifra confirm that an HTTP application is ready to receive traffic. The check calls an application GET route at regular intervals. When a failure is confirmed, the instance is restarted automatically to try to recover the service.

The feature is optional per project and depends on the selected plan. It is designed for applications that need continuous validation beyond the initial publication. For the complete publication flow, see Deployment and How to Create an HTTP Project.

Check whether the plan includes the feature

The plan catalog (GET /v1/project/plans) reports in capabilities.healthcheck whether the plan makes health checks available for HTTP projects. Today the feature is included from the Premium plan up. In the catalog, look for:

{
  "plan": "premium",
  "capabilities": {
    "healthcheck": true
  }
}

When the value is false, the option cannot be enabled. Projects on plans without the feature continue to work normally without a health check.

Health check availability comes from the plan: a project can enable it only when its plan includes the feature. If you need this feature and do not see the option in the Console, check the current plan or contact your organization administrator.

Configure a GET route

Create a simple route in the application, such as /health, and make it return an HTTP status between 200 and 299 when the application is ready. The path must start with / and cannot contain a domain, query string, or fragment.

Node.js example:

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' })
})

A 204 No Content response is also valid when the application does not need to send a body. Do not use redirects as a success response: the health check considers only 2xx responses healthy.

The route should respond quickly and avoid unnecessary dependencies. If the application depends on a database or another service to work, use a short and predictable validation without running heavy queries or exposing secrets in the response.

The equivalent project setting is:

{
  "healthcheck": {
    "enabled": true,
    "path": "/health"
  }
}

The check interval is fixed at 1 minute. The timeout and failure threshold are defined by Zenifra and cannot be configured in this version.

Understand the check behavior

After the health check is enabled:

1. Zenifra calls the configured route with GET every 1 minute.
2. A 2xx response indicates that the instance is healthy.
3. A 3xx, 4xx, or 5xx response, timeout, or connection failure indicates a failure.
4. When the failure is confirmed, the instance is restarted automatically.
5. The current state and observed events are available for review.

The restart can cause brief unavailability while the application starts responding again. A health check does not change application code or replace availability tests; it is an operational safeguard to recover instances that stopped responding correctly.

Failures remain available for 30 days. Each public record includes the occurrence time and the HTTP status when available. Internal instance details, response bodies, headers, secrets, and other sensitive information are not part of the public history.

Configure it in the Console

To configure the feature in the Console:

1. Open Projects and select an HTTP project.
2. Click Edit.
3. In the Application healthcheck section, turn on Enable healthcheck and enter the Check path, such as /health.
4. Click Save healthcheck.
5. Use the Failures in the last 30 days table to confirm the check results.

The section appears only when the project's plan returns capabilities.healthcheck: true. Existing projects can also enable the feature after creation as long as the plan is eligible. Disabling the health check stops new checks, preserves the last configured route, and does not delete recorded history.

Use the CLI

The CLI provides the same Console features for queries and automation:

zenifra project healthcheck get --project <id>
zenifra project healthcheck set --project <id> --path /health
zenifra project healthcheck disable --project <id>
zenifra project healthcheck failures --project <id> --page 1 --limit 20

Add --json to use command output in scripts or pipelines:

zenifra project healthcheck get --project <id> --json
zenifra project healthcheck failures --project <id> --json

Failure queries return only the previous 30 days of history. For authentication and other commands, see Deploy and Automation CLI.

Use the public API

The setting can also be managed through the authenticated project API:

GET /v1/project/:id/healthcheck
PATCH /v1/project/:id/healthcheck
GET /v1/project/:id/healthcheck/failures?page=1&limit=50

To enable or change the route:

{
  "healthcheck": {
    "enabled": true,
    "path": "/health"
  }
}

To disable it, send only enabled: false. The last path is preserved:

{
  "healthcheck": {
    "enabled": false
  }
}

The configuration response includes available, interval_seconds, and retention_days, along with the current setting. The failure response contains occurred_at, status_code when available, and pagination. Authorization and plan entitlement remain server-side responsibilities; the Console and CLI do not replace that validation.

Troubleshooting

The option does not appear in the Console

Confirm that the project is HTTP and that the plan returns capabilities.healthcheck: true. If the plan is not eligible, the setting cannot be enabled. A plan change may take a few moments to appear on the project.

The check returns 404 or 405

Review the path saved on the project and confirm that the application exposes that exact route with the GET method. The path must start with / and must not include the full domain.

The check returns 3xx, 4xx, or 5xx

Update the route to return 2xx when the application is ready. Redirects, required authentication, error pages, and validation responses are not considered success.

The instance keeps restarting

Test the route directly at the public URL and confirm that it responds quickly. Also confirm that the project uses the same port configured by the application and that the route does not depend on slow or unavailable calls. Review application logs in the Console to identify the failure reason.

There are no failures in the history

History records failures observed after activation and keeps records for 30 days. When the feature is disabled, new checks stop running; previous failures remain available during the retention period.

For other scenarios, see Troubleshooting.

Next steps

• Change HTTP Project Settings
• HTTP Metrics
• Deploy and Automation CLI
• Troubleshooting

FAQ

Can I use any path for the health check?

Yes, as long as it is an absolute application path, starts with /, and is served with GET. Do not include a domain, query string, or fragment.

Which HTTP status is considered healthy?

Any status from 200 through 299. 3xx, 4xx, 5xx, timeouts, and connection failures are considered failures.

Can I change the 1-minute interval?

No. The interval is fixed at 1 minute in this version. Zenifra also defines the timeout and failure threshold.

Does the feature work for existing projects?

Yes. An existing HTTP project can enable the health check when its plan includes health checks (capabilities.healthcheck: true). The setting takes effect after it is saved.

What happens to history when I disable the feature?

History is not deleted. It remains available for up to 30 days, while new checks stop running.