Health check da aplicação

O health check chama uma rota GET da sua aplicação HTTP a cada 1 minuto e reinicia a instância quando uma falha é confirmada. Estas rotas permitem consultar e alterar a configuração e listar as falhas registradas. O comportamento completo do recurso está em Health checks para projetos HTTP.

Autenticação e permissões

As rotas aceitam uma API Key da organização (x-api-key: znf_... ou Authorization: Bearer znf_...) ou um token de usuário com x-organization-id.

Rota	Scope em `project:<project-id>`	Limite
`GET /v1/project/:id/healthcheck`	`project.read`	100 por minuto
`PATCH /v1/project/:id/healthcheck`	`project.instances.update`	20 a cada 5 minutos
`GET /v1/project/:id/healthcheck/failures`	`project.metrics.read`	100 por minuto

owner tem acesso completo; assistant, member e API Keys precisam do scope da ação. As rotas valem apenas para projetos HTTP; para outros tipos a resposta é 400 com healthcheck is available only for HTTP projects.

Consultar a configuração

GET /v1/project/:id/healthcheck

{
  "status": "success",
  "data": {
    "available": true,
    "healthcheck": { "enabled": true, "path": "/health" },
    "interval_seconds": 60,
    "retention_days": 30
  }
}

Campo	Descrição
`available`	`true` quando o plano do projeto inclui health check. É o mesmo valor de `capabilities.healthcheck` em `GET /v1/project/plans`
`healthcheck.enabled`	Se a verificação está ativa
`healthcheck.path`	Rota verificada. Projetos que nunca configuraram o recurso retornam `{ "enabled": false, "path": "/health" }`
`interval_seconds`	Intervalo entre verificações (fixo em 60)
`retention_days`	Período em que as falhas ficam disponíveis (fixo em 30)

Ativar, alterar ou desativar

PATCH /v1/project/:id/healthcheck

Campo	Tipo	Obrigatório	Descrição
`healthcheck.enabled`	boolean	Sim	`true` ativa; `false` desativa
`healthcheck.path`	string	Com `enabled: true`	Caminho absoluto de 1 a 256 caracteres, começando com uma única `/`, sem domínio, query string ou fragmento

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

A resposta confirma a configuração aplicada:

{
  "status": "success",
  "data": {
    "healthcheck": { "enabled": true, "path": "/health" },
    "interval_seconds": 60,
    "retention_days": 30
  }
}

Para desativar, envie { "healthcheck": { "enabled": false } }. A última rota configurada é preservada e o histórico de falhas continua disponível. Desativar é permitido em qualquer plano; ativar exige um plano com o recurso.

Código	Situação
`400`	Corpo inválido, caminho fora do formato, projeto que não é HTTP ou plano não encontrado
`403`	Plano sem health check (`HEALTHCHECK_NOT_AVAILABLE_FOR_PLAN`) ou scope insuficiente
`404`	Projeto não encontrado (`project not exists`)
`429`	Limite de requisições excedido

Listar falhas

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

Parâmetro	Tipo	Padrão	Descrição
`page`	inteiro	`1`	Página, a partir de 1
`limit`	inteiro	`50`	Itens por página, de 1 a 100

{
  "status": "success",
  "data": {
    "failures": [
      { "occurred_at": "2026-10-08T12:03:00.000Z", "status_code": 503 }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 },
    "retention_days": 30
  }
}

As falhas vêm da mais recente para a mais antiga e cobrem apenas os últimos 30 dias. status_code é o status HTTP devolvido pela aplicação e fica ausente quando não houve resposta, como em timeout ou falha de conexão.

Exemplo

curl -X PATCH "https://api.zenifra.com/v1/project/6650f1a2b3c4d5e6f7a8b9c0/healthcheck" \
  -H "x-api-key: znf_..." \
  -H "Content-Type: application/json" \
  -d '{"healthcheck": {"enabled": true, "path": "/health"}}'

Próximos passos

Confira no catálogo de planos quais incluem o recurso.
Ative o health check já na criação com config.healthcheck em Criar, listar e remover projetos.
Investigue falhas com Métricas e Logs.
Configure alertas por e-mail para a aplicação.