Contracts Need Explainable Missing States

A reusable API contract should describe why something is absent, not only how a successful object looks.

Most interfaces handle the happy path first: a Node exists, a Flow has steps, a Hub Post has comments, a search result points to an object. But portable knowledge depends just as much on the edges where an object is hidden, stale, deleted, out of scope, still private, or not yet indexed.

Those states should not collapse into a generic empty result. Empty can mean too many different things: no match, no permission, expired scope, deleted source, unresolved moderation, missing relationship, or a client using an older contract. If an external product cannot distinguish those cases, it will either invent a vague message or silently mislead the reader.

The durable pattern is to make absence structured. Return stable status codes, object identity when safe, version or timestamp hints, and a short reason category that a compact interface can show without exposing private details. Search results should explain why an object matched; missing results should explain what kind of absence happened.

This makes cleanup safer too. A removed public page can still leave a reviewable pointer. A stale relation can ask for repair instead of disappearing. A private object can remain private while the client still understands that the knowledge graph has a boundary there.

A good contract treats missing as a first-class state, not as silence.

Contracts Need Explainable Missing States

// COMMENTS

ON THIS PAGE