Statuses and reasons

Every value carries a status. It is not decoration: it is how you tell a number you can act on from one you cannot, and the platform will not make that judgement for you.

status	what it means	what to do
present	received within the layer’s freshness bound	use it
stale	received, but older than the bound	it compares as unknown; decide whether the age matters to you
missing	nothing was received	there is no value; the reason says why
not_published	the venue does not publish it at all	a fact about the venue; it will not appear later
off	the platform does not collect it for this listing	a choice, and it can change

The last two are kept apart deliberately. not_published is a fact about the exchange; off is a decision the platform made. Merging them into “no data” would hide which of the two you could do something about.

Why a stale value is returned at all

Because the alternative is worse. A platform that dropped stale readings would answer a screen with fewer venues and no explanation, and a bot would read that as “this venue has no funding” rather than “this reading is eight minutes old”. The value comes back with its true age, and comparisons involving it answer unknown — which is a third answer, not a failure.

Every reason a value is null

reason	why
not_retained	the instant is older than what is kept for this listing
gap	a period inside the window has no candle or sample
insufficient_history	the series starts after the window needed
policy_off	the platform does not collect this for the listing’s group
venue_capability	the venue does not publish it
no_value	nothing was received, or the formula has none (÷0, a flat window)
band_truncated	the received book did not reach the edge of the band
unit_unknown	a conversion was asked for and the contract size is not known
unmapped	the listing belongs to no instrument

A reason is informative and never queryable: you cannot branch on one inside DQL. The platform will tell you why it has nothing; it will not let you build a condition on its own excuses.