Status e healthcheck

Use o endpoint público de healthcheck para monitorar a disponibilidade da API BS Finance em tempo real. A resposta inclui o status geral e o estado de cada subsistema (banco de dados, malha Pix, fila de webhooks).

Endpoint

GET/health

Endpoint público — não requer cabeçalho Authorization. Ideal para uso em sondas de uptime, balanceadores e dashboards de observabilidade.

Exemplo de requisição

curl -X GET https://api.pix.nixfin.com.br/health

Resposta — operacional

{
  "status": "operational",
  "version": "v1",
  "region": "br-sa-1",
  "timestamp": "2026-04-23T14:02:11Z",
  "components": {
    "api": "operational",
    "database": "operational",
    "pix_network": "operational",
    "webhooks_queue": "operational",
    "boletos": "operational"
  },
  "latency_ms": 38
}

Resposta — degradada

{
  "status": "degraded",
  "version": "v1",
  "region": "br-sa-1",
  "timestamp": "2026-04-23T14:02:11Z",
  "components": {
    "api": "operational",
    "database": "operational",
    "pix_network": "degraded",
    "webhooks_queue": "operational",
    "boletos": "operational"
  },
  "incident_id": "inc_7f3a2b",
  "message": "Latência elevada na malha Pix do BCB."
}

Códigos de status HTTP

Tabela de referência dos códigos retornados pela API BS Finance em qualquer endpoint.

Código	Significado	Ação recomendada
200	OK — requisição processada com sucesso.	Prosseguir normalmente.
201	Created — recurso criado (cobrança, transferência, webhook).	Persistir o `id` retornado.
202	Accepted — operação assíncrona em fila.	Aguardar webhook ou fazer polling pelo `id`.
204	No Content — sucesso sem corpo de resposta.	Não tentar parsear JSON.
400	Bad Request — payload inválido ou parâmetros faltando.	Validar campos antes de reenviar; não retentar automaticamente.
401	Unauthorized — token ausente, expirado ou inválido.	Renovar o token via `/oauth/token`.
403	Forbidden — credencial sem permissão para o recurso.	Revisar escopos da aplicação no painel.
404	Not Found — recurso inexistente.	Confirmar `id` e ambiente (sandbox vs produção).
409	Conflict — idempotency-key reutilizada ou recurso duplicado.	Consultar pelo `Idempotency-Key` para obter o resultado original.
422	Unprocessable Entity — regra de negócio violada (ex.: saldo insuficiente).	Tratar pelo campo `error.code` no payload.
429	Too Many Requests — limite de taxa atingido.	Respeitar o cabeçalho `Retry-After` e aplicar backoff exponencial.
500	Internal Server Error — falha não esperada na API.	Retentar com backoff; abrir chamado se persistir.
502 / 503 / 504	Indisponibilidade temporária ou janela de manutenção.	Retentar com backoff exponencial e jitter (até 5 tentativas).

Estados do healthcheck

operational — todos os subsistemas funcionando dentro do SLA.
degraded — API responde, mas com latência elevada ou falhas parciais em algum componente. Operações podem ser mais lentas.
partial_outage — um ou mais componentes indisponíveis. Os demais continuam operando normalmente.
major_outage — indisponibilidade generalizada. Consulte status.bsfinance.tech para acompanhar o incidente em tempo real.

Boas práticas: faça polling do /health no máximo a cada 30 segundos. Para alertas de produção, recomendamos assinar a página de status oficial em vez de bater no endpoint continuamente.

Ambientes

Erros e respostas