Statuses and reasons

Every value DEBYKO returns carries a status. It is how you tell a number you can act on from one you cannot, and the platform does not make that judgement for you. A value that is not present is never returned as a number, and a missing value is never written as zero.

The five statuses

status	what it means	comes with a number	what to do
`present`	Received, and still within its validity horizon (`valid_until`) and any bound the request set.	yes	Use it.
`stale`	Received, but no longer current. The value is withheld.	no, withheld	It compares as unknown. Ask with `allow_stale` to see it under `withheld`, for a post-mortem only.
`missing`	Nothing was received.	no, null	There is no value. The reason says why.
`not_published`	The venue does not publish it at all. A fact about the venue.	no, null	It will not appear later.
`off`	The platform does not collect it for this listing’s group. A choice, and it can change.	no, null	Ask for another listing, or for the plan or policy to change.

not_published and off are kept apart on purpose. 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.

A value that is stale is withheld because a number that is no longer current, left in the value field, is read by any client that forgets to look at the status, and a backtest that forgets once has used information that was not true at the time. How long each value is good for is on Freshness and cadence.

An example answer for each case

The shape of one layer in POST /v2/snapshots. The numbers are illustrations; the shape is the published LayerReading schema, and every example below is checked against it.

present. A current rate, with its interval and the 8-hour restatement.

{
  "status": "present",
  "venue_ts": null,
  "received_at": "2026-09-23T12:00:04Z",
  "age_ms": 1000,
  "valid_until": "2026-09-23T12:05:04Z",
  "horizon_source": "assumed",
  "anchor": "receipt",
  "values": {
    "funding": 0.0000125,
    "funding_interval": 3600000,
    "funding_8h": 0.0001
  },
  "units": {
    "funding": "fraction",
    "funding_interval": "ms",
    "funding_8h": "fraction"
  }
}

stale, halted. The venue halted the listing. The last rate is not a market, so it is not in values.

{
  "status": "stale",
  "reason": "halted",
  "venue_ts": null,
  "received_at": "2026-09-23T11:52:00Z",
  "age_ms": 485000,
  "valid_until": "2026-09-23T11:57:00Z",
  "horizon_source": "assumed",
  "anchor": "receipt",
  "values": {}
}

stale, connection_lost. A value pushed only on change, whose connection broke. Nothing is in values.

{
  "status": "stale",
  "reason": "connection_lost",
  "venue_ts": null,
  "received_at": "2026-09-23T11:20:00Z",
  "age_ms": 1920000,
  "valid_until": null,
  "horizon_source": "connection",
  "anchor": "receipt",
  "values": {}
}

missing. Nothing has been received for this layer.

{
  "status": "missing",
  "reason": "no_value",
  "venue_ts": null,
  "received_at": null,
  "values": {}
}

not_published. The venue publishes no open interest for the listing. It will not appear later.

{
  "status": "not_published",
  "reason": "venue_capability",
  "venue_ts": null,
  "received_at": null,
  "values": {}
}

off. The platform does not collect this layer for the listing’s group.

{
  "status": "off",
  "reason": "policy_off",
  "venue_ts": null,
  "received_at": null,
  "values": {}
}

Every reason a value can be null or stale

A reason is informative and never queryable: you cannot branch on one inside DQL. The platform tells you why it has nothing; it does not let you build a condition on its own excuses. The first group is the reasons of a stale value.

reason	what it means
`horizon_passed`	stale: no new value arrived within the value’s horizon (twice its interval, or until the next settlement).
`connection_lost`	stale: a value pushed only on change, and the connection that delivered it was recorded lost.
`state_lag`	stale: the platform’s own live projection lagged. The venue and its connection were fine.
`source_error`	stale: the venue refused our requests for the layer (an error status, not a rate limit) since the value arrived.
`horizon_unknown`	stale: no cadence fact covers the value, so there is no proof it is current.
`freshness_bound`	stale: older than the `freshness` bound the request set, which is tighter than the horizon.
`halted`	stale: the venue said it does not trade the listing at that instant. The figures are the venue’s last, not a market.
`no_update`	stale: the value is pushed only on change, its connection is alive, and it has not changed for longer than its pair’s no-update threshold.
`venue_capability`	not_published: the venue does not publish it.
`policy_off`	off: the platform does not collect it for this listing’s group.
`no_value`	missing: nothing was received, or the formula has no value (a division by zero, a flat window).
`funding_continuous`	the venue accrues funding continuously and never settles, so there is no settlement interval, next settlement or countdown. `funding` and `funding_8h` are unaffected.
`not_retained`	the instant asked about is older than what is kept for this listing (`retention_from`).
`gap`	a period inside the window has no candle or sample.
`collector_gap`	the platform recorded a hole in its collection there; `gap_cause` says what.
`insufficient_history`	the series starts after the window the function needs.
`reference_not_listed`	`corr` or `beta`: the reference instrument has no listing on the venue it is read on.
`not_in_scope`	`ref`: the instrument it reads is not listed on that venue at the instant, is halted there, or a layer its expression reads is `off` or `not_published`.
`band_truncated`	the received book did not reach the edge of the depth band.
`partial_coverage`	the book is a window of the venue’s (`coverage_bps` says how far each side reaches) and the band’s edge is beyond it; the side is null, never the sum of the part that is known.
`unit_unknown`	a conversion to the base asset was asked for and the contract size is not known.
`unmapped`	the listing belongs to no instrument.
`no_venues`	a quantifier or aggregate had no listing left in its scope, so its value is unknown.

Settled

An instant is settled once late arrivals can no longer change an answer about it; the catalogue states how long that takes (settle_after in GET /v2/dql/catalogue). Every answer says whether its instant is settled. A false is not a warning: it is the honest state of a question asked about the present, and it means the same query may answer differently a little later. See Point in time.

The words Studio prints in a cell

Studio’s funding matrix prints a number only for a LIVE value; in place of a number a cell carries one word, and every word is one of the statuses and reasons above or one of three Studio adds: delayed (a present value older than half of its horizon, not yet stale; it is shown, never compared), migrated (the listing’s source API was retired, so it is no longer read) and not collected (status off: the platform does not collect the listing’s group). A rate the platform cannot restate to 8 hours, because the venue does not document its unit or interval (edgeX), is not_published with reason venue_capability: the cell says NOT PUBLISHED, not a guessed figure. The funding embed and its SVG card print the same words, and say MISSING for the whole table when its read fails or times out, NOT COLLECTED for an instrument the platform does not collect.

Where the words come from

The statuses and reasons on this page are the members of the Status and NullReason schemas of the reference, and the page is rendered from them: a status or reason the API gains cannot be missing here. History adds one word to a row of interval mode, gap: a period the platform collected and holds no reading of. Why such a period is empty is collector_gap with a gap_cause, or not_retained.