Building a status page for the Bullion API that explains its incidents

I built a public status page for the Bullion API in July, before there was a real incident to put on it. Features and documentation don't help someone who can't rely on the API being available. I wanted the page to show that I'm watching the service and what I count as healthy, and to give me somewhere to explain a change when one happens.

What it checks

Each component on the page says what its check is:

• API: Health check: GET /health, expecting a 200, with no auth or quota.
• Auth endpoint: GET /api/auth/get-session, expecting a 200 with no session.
• Marketing site: the home page answers.
• Daily refresh cron: fails if the last successful price refresh is more than 36 hours old, outside planned skip windows.
• Central-bank reserve refresh: the same 36-hour rule for the reserves data.
• Central-bank gold refresh: degraded when any supported source is overdue for how often it publishes.

Getting to that list meant removing a check and correcting two others. The first version had a database-backed signal for the refresh process. I removed it, because the API could keep serving cached data after the refresh had stopped and that check couldn't reliably tell the difference. The refresh components now judge the last successful run instead.

The health response only became actionable once it returned an unhealthy status for an unreachable database or stale refresh data. And the auth probe first expected a 401 from an unauthenticated request, when the endpoint really returns 200 with an empty user. Treating the real response as a failure would have produced a convincing but false incident.

Incidents from open to close

A page that only shows the current state leaves people to work out what happened. So each incident is recorded from open to close, with its own page and timeline.

An incident opens after two consecutive failed checks and closes after three consecutive successful ones. A single blip doesn't open an incident, and a component that is still flaky doesn't flap between open and closed. Further failures while an incident is open don't add duplicate updates. Once an incident has closed, a new run of failures opens a new incident and the old one stays as it was.

Since July the page has built up a history of real incidents, which is what it was for.

Notifications, the badge and the JSON endpoint

When an incident opens or closes, I get notified, and subscribers who confirmed their email address get the update. The marketing site shows a live status badge that links to the full page.

If an email or webhook fails to send, the monitoring loop still records the check and carries on, so a delivery problem can't take the monitoring down with it.

The page and the JSON endpoint share one read model, so both use the same component order, the same latest check and the same uptime figures. Before I consolidated it, they each worked out the status summary themselves, so they could have disagreed.

The page reports what its checks can establish, and nothing more. It doesn't say every dependency is healthy.