A status page should explain incidents, not just show green

I have started to think of a status page as part of the API product, not as a decorative page that gets built after the important work is finished. An API can have excellent features, sensible documentation, and a polished dashboard. None of that helps a customer who cannot rely on the service being available.

That is why I built a public status surface for Bullion API before the first real incident. The point was not to make a green badge that says everything is fine. The point was to make an operational promise visible: I am watching the service, I have defined what I consider healthy, and I have a way to explain a change when one happens.

You can see the result on the Bullion API status page. It is deliberately small. That is a strength.

Reliability is part of the product

Customers do not experience an API as a collection of implementation details. They experience successful requests, useful responses, and the confidence that their integration will keep working. Operational reliability belongs in that same product conversation.

The status page gives customers evidence that the API is actively monitored. It also gives me a place to be clear about what the monitoring means. A green state is only useful when somebody can understand which signals produced it and how recently they were checked.

This changes the role of the page. It is not a marketing claim about perfect uptime. It is a public view of the checks and decisions behind the service. That is more credible, especially before there is an incident history to point at.

A check needs a customer-facing reason

The first version of the status system checked several components, including a database-backed signal for the scheduled refresh process. That check was technically reasonable, but it was not the best signal for the page. The API could still serve cached data while the refresh process had stopped, and the status check could not reliably distinguish that situation from normal operation.

I removed that check and kept the signals that answer a more useful question: can the public API and its important paths respond as customers expect? Adding another internal check would have made the system look more complete without making the answer more accurate. If the missing signal becomes important, I can add a direct heartbeat from the refresh job later.

This is the same principle I use when designing health checks. A check should have a clear failure meaning. “The database answered” is not automatically the same as “the product is working”. A status page should prefer a small set of evidence-backed checks over a catalogue of dependencies that nobody can interpret.

History matters more than a snapshot

The page records component checks, but a status page that only reports the current state still leaves customers to reconstruct what happened. I wanted the system to describe an incident as a lifecycle.

The incident state machine opens an incident after consecutive failures and closes it after consecutive successful checks. That gives the system some resistance to a single transient request failure, while still making recovery visible. A failure while an incident is already open does not create a stream of duplicate updates. Once an incident closes, a later failure can create a new event rather than rewriting the old one.

The exact thresholds are less important than the shape of the decision. The status page needs to distinguish a noisy signal from a sustained problem, then preserve enough history for a customer to see that the problem was acknowledged and resolved. I do not want to imply that the API has already had an outage. I want the product to be ready to explain one honestly if it occurs.

That is why a timeline is more useful than a colour alone. Green tells me about now. Incident history explains change.

Notifications make the status page useful

The public page is only one side of the design. When an incident opens or closes, the system also notifies the operator and, for confirmed subscribers, sends the relevant update. The marketing site displays a live status badge that links back to the full page.

Those surfaces serve different jobs. The badge gives a quick signal while someone is browsing the product. The status page gives context. Notifications give the people responsible for the service a prompt to act. A status system that only updates a page asks customers to discover the problem themselves.

I also kept notification failures separate from the health check itself. If an email or webhook fails, the monitoring loop should still record the check result and continue. The status system must not turn a secondary delivery problem into a larger outage in the monitoring path.

Honest limits are better than impressive coverage

The status page is not a claim that every dependency is healthy. It reports what the selected checks can establish. That boundary matters.

For example, the API’s health response became actionable when it returned an unhealthy status for an unreachable database or stale refresh data. An authentication probe also had to be corrected when the endpoint’s real unauthenticated response was 200 with an empty user, not 401. Treating the expected response as a failure would have produced a convincing but false incident.

I also consolidated the status read model so the public page and JSON endpoint use the same component ordering, latest-check selection, and uptime calculations. Customers should not get one interpretation in the browser and another from the API because two callers implemented the same rollup differently.

These details are not separate from the user experience. They are the user experience. A status page earns trust by being right about what it knows, explicit about what it does not know, and consistent wherever the status is displayed.

Build the explanation before you need it

I do not want a status page to prove that Bullion API will never have trouble. That is not a promise any honest system can make. I want it to show that operational reliability is being treated as part of the product before a customer has to ask about it.

The useful work is the preparation: choose signals that mean something to users, record state changes, notify the people who need to respond, and expose the same interpretation through every public surface. When the page is green, it should tell a customer why. When it is not, it should explain what changed and what happened next.

That is a much stronger promise than a green badge on its own.