> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data gaps

> Handle missing, stale, delayed, or unsafe 0xArchive market-data windows before they affect backtests, alerts, exports, or models.

A data gap is any condition where the payload is not safe enough for the job: missing records, stale ingestion, partial coverage, known incidents, replay gap events, or a route-family mismatch that makes the output misleading.

The correct response is not to hide the gap. A downstream system should know whether data was complete, delayed, degraded, or rejected. To decide whether data should be available before a job runs, start with [Data availability](/core-concepts/data-availability).

## Gap Types

| Gap type        | How it appears                                              | Response                                      |
| --------------- | ----------------------------------------------------------- | --------------------------------------------- |
| Freshness lag   | Latest ingestion is outside tolerance                       | Delay, mark stale, or stop                    |
| Coverage gap    | Venue, symbol, data family, or time window is not available | Narrow scope or choose another route          |
| Incident window | Known interruption overlaps the job window                  | Mark output and decide whether it can be used |
| Replay gap      | WebSocket replay emits a gap event                          | Stop or rebuild from a safe checkpoint        |
| Route mismatch  | Symbol belongs to another venue family                      | Correct the route before collecting data      |
| Plan gate       | Key cannot access the required depth or window              | Change plan, route, or job scope              |

## Required Handling

<Steps>
  <Step title="Check before the job">
    Use data-quality routes or a bounded probe before backtests, alerts, dashboards, exports, or model jobs.
  </Step>

  <Step title="Propagate the result">
    Store freshness, incident, coverage, and request-ID context with the downstream output.
  </Step>

  <Step title="Fail visibly">
    If the gap matters for the job, mark the output incomplete or stop instead of filling silently.
  </Step>

  <Step title="Resume with an explicit policy">
    For replay or historical pulls, resume from a known safe checkpoint, not from whatever local state remains.
  </Step>
</Steps>

## When Gaps Matter Most

Gaps matter most when output becomes evidence: backtests, trading research, strategy comparisons, risk models, alerts, customer dashboards, exports, and automated agent decisions. A stale latest quote may be acceptable for a UI smoke test and unacceptable for an alert. The job has to define the tolerance.

For HIP-4, a price interpretation mistake can look like a data gap because probability-like values are being treated as USD prices. For HIP-3, a stripped builder prefix can send a request to the wrong family. For Spot, a pair-shaped symbol should stay under the Spot route family when the prompt asks for Spot.

## Gap Decision Checklist

When a gap appears, store the decision instead of hiding it in logs.

| Field          | Capture                                                               |
| -------------- | --------------------------------------------------------------------- |
| Gap source     | Freshness, coverage, incident, replay, route mismatch, or access gate |
| Affected scope | Venue family, symbol, data family, and UTC window                     |
| Tolerance      | Whether the downstream job can use stale, partial, or delayed data    |
| Action         | Continue with label, narrow scope, delay, rebuild, rerun, or stop     |
| Trace          | Route, request ID, replay manifest, incident ID, or coverage response |

## Next Step

Use [Data quality](/data-quality) for the gate, [Reliability and gaps](/guides/reliability-and-gaps) for workflow design, and [WebSocket backtesting](/websocket/backtesting) when replay events feed research.