# Freshness, partial and stale records

> Use the snapshot metadata to tell how current a record is, what's missing, and whether a source failed.

Health systems don't always return everything, and syncs fail. Every snapshot and category page carries `meta` so you can say what you have.

## Read the metadata

| Field | Meaning |
| --- | --- |
| `syncStatus` | `complete`, `partial`, or `not_started`. |
| `dataAsOf` | The oldest source watermark among the sources in this response. |
| `lastSuccessfulSyncAt` | The latest finish time among each source's most recent complete or partial sync. |
| `availableCategories` | Categories where at least one source returned data in its last usable sync. |
| `missingCategories` | Categories FinchNode couldn't read. |
| `warnings` | Source- or category-level problems, each with a `code` and `message`. |

A category counts as available when any of its resource types came back, so a partly read category may not appear in `missingCategories`. Check `warnings` too.

## Before you say "no records"

An empty category means "none on file" only when:

- `syncStatus` is `complete`,
- the category is in `availableCategories`, and
- no warning names it.

Otherwise say it couldn't be loaded. A source that hasn't synced yet returns empty data with no warnings and `syncStatus: "not_started"`.

## When a source fails

If a source synced before and its latest sync failed, `syncStatus` is `partial` and `warnings` includes something like this (synthetic):

```json
{
  "code": "source_unavailable",
  "source": "northstar-health",
  "message": "The latest sync from this source did not complete. Records shown are from its last successful sync.",
  "retryable": true
}
```

Show those records with their age, from `dataAsOf`. A sync that failed partway may still have applied some changes before it stopped.

## Continuous sync

With continuous sync, FinchNode re-imports every 6 hours by default. A share gets it only when all three hold:

1. Your application is set to continuous.
2. The patient opted in on the consent screen.
3. The health system allows ongoing access.

Otherwise it's one-time. The receipt's `syncMode` says which you got.

## Sync webhooks

These arrive only for continuous shares, after a scheduled re-import. The first import doesn't send them; `consent.granted` covers it.

| Event | When |
| --- | --- |
| `sync.completed` | A re-import finished with everything it asked for. |
| `sync.partial` | A re-import finished with something missing. |
| `sync.failed` | A re-import failed. `data.code` and `data.retryable` say why and whether it will try again. |
| `records.updated` | A re-import changed or deleted records. |

If a failed refresh needs the patient to sign in again, they reconnect from their FinchNode account.