Health checks de uma API: por que um 200 OK não garante que funcione
Publicado em 2026-10-26 por frfrand
Projetar verificações de liveness e readiness sem saturar o banco de dados
A rota /health retorna 200 e todos felizes. Mas acontece que o PostgreSQL está caído e não é possível criar uma única reserva. Um health check útil deve distinguir «o processo está vivo» de «consigo atender tráfego».
Vamos baixar a bola: o que significa, como testar e o que acontece quando você usa com clientes ou informações reais. A maioria dos problemas não se resolve com um botão mágico, mas com passos que você pode repetir e medir.
O que são health checks de uma API e por que importam
Liveness indica se vale a pena reiniciar um processo que não responde; readiness sinaliza se está preparado para receber solicitações. Verificar todas as dependências em cada liveness pode gerar reinícios em cascata quando falha um banco externo.
Uma coisa é uma demo funcionar cinco minutos e outra é manter um serviço todos os dias. Para isso você precisa de limites, permissões, registros de atividade e procedimentos para resolver falhas sem improvisar.
Exemplo de implementação ou diagnóstico
from fastapi import FastAPI
app = FastAPI()
@app.get('/live')
def live():
return {'status': 'alive'}
# /ready debería consultar dependencias necesarias con timeout corto
# y devolver 503 si no puede atender trabajo realÉ uma referência didática, não um modelo que você deve executar às cegas em produção. Substitua os valores de exemplo, escolha identidades com permissões mínimas e certifique-se de que nenhuma chave sensível termine em um log ou repositório.
Como eu colocaria para funcionar
- Crie um endpoint de liveness muito leve, sem depender de uma consulta lenta.
- Projete readiness de acordo com as dependências críticas para a funcionalidade principal.
- Use timeouts curtos para não saturar o banco de dados durante um incidente.
- Verifique o que o balanceador faz ante 503 e como o serviço se recupera.
- Adicione monitoramento funcional externo para comprovar operações reais, não apenas HTTP 200.
Após cada etapa, verifique um resultado concreto: uma ação autorizada, um status HTTP, uma tarefa processada, um custo registrado ou uma métrica estável. Se algo não funcionar, verifique qual foi a primeira falha antes de tentar novamente em loop.
Um exemplo que pode aparecer em um projeto real
Uma API de tours responde a /live enquanto está ativa, mas /ready retorna 503 se não conseguir consultar a disponibilidade pelo PostgreSQL. Isso ajuda o sistema a não enviar reservas para uma instância que não pode atendê-las.
Se esse aplicativo tiver vários clientes, separe contextos e recursos. É especialmente importante quando um chatbot ou um agente pode consultar dados: a facilidade de conectar ferramentas não deve pular os limites de privacidade e autorização.
O erro mais comum
Não faça uma consulta cara em cada health check. Se todos os contêineres consultarem o banco de dados várias vezes por segundo, o monitoramento pode se tornar parte do problema.
Uma configuração com bons padrões ajuda, mas não elimina a necessidade de testes. Para serviços que gravam dados ou disparam ações, considere retentativas, duplicatas e falhas no meio do caminho.
Onde entra o ArduMaker?
Em aplicações hospedadas no ArduMaker, combine o estado dos serviços com testes de saúde e monitoramento externo. Um VPS ligado não garante que a aplicação cumpra sua função.
Com o ArduMaker você pode hospedar o backend em um VPS, fazer deploy a partir do Git, configurar domínio HTTPS e utilizar ferramentas de bancos, serviços e MCP de acordo com o projeto. Isso facilita reunir operações em um ambiente, embora as regras de negócio e de segurança continuem sendo responsabilidade do software.
O que mediria para saber se melhorou
Não mediria apenas «funciona/não funciona». Também revisaria consumo de recursos, erros, tempos de resposta ou gasto de API, conforme a funcionalidade. Defina uma medida de sucesso antes da mudança e compare com o mesmo cenário depois.
Se um dado parecer estranho, verifique a amostra e a janela temporal. Uma média pode esconder casos extremos, e uma única execução bem-sucedida não demonstra que uma automação suporte milhares de solicitações.
Perguntas frequentes
Preciso de uma infraestrutura grande para começar? Não necessariamente. Primeiro resolva o problema com uma arquitetura simples e meça o ponto onde ela começa a ficar aquém.
O que acontece se o provedor externo falhar? Você precisa de timeouts, política de tentativas e uma resposta útil para o usuário. Não assuma que APIs externas estão sempre disponíveis.
Como mantenho o controle? Registre eventos importantes, separe permissões e conserve um procedimento testado para desfazer alterações ou recuperar informações.
Referências para seguir
A ideia final: automatizar e medir vale a pena quando você também sabe detectar um erro, limitar seus efeitos e se recuperar.