Skip to content

New paid orders and subscriptions are retired. Existing records, settlement and refunds remain available through your account.

Handle staleness gracefully

The platform tells you when it doesn't know.

Cambridge TCG is substrate-honest about its own freshness. Every response declares when it was last known to be true (`as_of` or `magnitude_freshness`), what the platform's intent on freshness is (`freshness_seconds` or `magnitude_freshness.decimal_age_seconds`), and what to do when an answer is unavailable. This guide names the patterns.

5 min· 3 steps· last verified 2026-05-14

Prerequisites

  • • You've called at least one endpoint

Steps

  1. 1

    Read _meta.as_of vs _meta.retrieved_at

    Two distinct timestamps. `retrieved_at` is when the response was *produced* (server clock). `as_of` is when the underlying data was last *known to be true*. For current-state endpoints they're often equal; for temporal slices they differ. Aggregates report the *earliest* as_of across contributing rows (response is only as fresh as its stalest component).

  2. 2

    Detect 'never_run' vs 'unreachable' vs 'stale'

    Substrate-honest absence pattern. Three distinct shapes from /api/v1/sources/[id]: `health.state: "healthy"` (within budget); `"stale" / "very_stale"` (past budget); `"never_run"` (no ingest_run rows); `"unknown"` (wholesale unreachable). Render different state pills for different absences.

  3. 3

    Honour `_meta.deprecation` when present

    If `_meta.deprecation: { sunset, replacement }` is non-null, the endpoint is being retired. Your code should switch to `replacement` before `sunset`. We give 12-month minimum deprecation windows. The sunset date returns HTTP 410 with the same `deprecation` pointer.

Common gotchas

  • Don't pretend 0 means 'no records'

    When admin/storefront reads fail, `safe()`/`safeCount()` return -1 / sentinel — they degrade visibly to '—' on the UI. Your downstream should do the same. Zero is a real value; 'I don't know' is a different value. Don't collapse them.

  • Cached responses report a stale as_of

    CDN-cached responses still emit the same `_meta.as_of` they were rendered with. If you need a strictly-fresh read, send `Cache-Control: no-cache` — but only when you must; respect the budget otherwise.

Next guide

How to be a polite client →

Etiquette + identification + the contact channel.

See also