Caching and stale data

Every registry behaves differently. Some respond instantly, some update daily or monthly, and some occasionally become unavailable.

VerifyVAT smooths these differences by applying a two-tier caching model. The goal is to provide stability and predictable behaviour without hiding important freshness signals.

This page explains how caching works, what “stale” means, and how to interpret the metadata returned in process.sources[] as part of the response described in Verify an ID.

What is cached

Our engine caches single registry slices independently, not merged results. This matters because a single verification request may query multiple registries, as explained in Cross-registry checks.

Each registry slice is finalized before caching, and it includes everything from the raw registry response to all enrichments derived from it, like normalised addresses, inferred components, geolocation, and timeline events.

Cache layers

Our engine uses a two-layer caching model.

Primary: 24-hour Redis cache

This layer is designed for speed and predictability, and is referred to as fresh-cache.

• Stores only non-error responses from registries
• TTL is always 24 hours, regardless of the registry’s own update frequency
• If a Redis entry exists, it is returned before even querying the registry

This ensures predictable behaviour. Once a registry response has been observed, the data produced from it will not change within the following 24-hour window.

Secondary: 30-day fallback DB

This layer is designed for resilience when registries are unavailable, and is referred to as stale-cache. If a registry is unavailable (maintenance, throttling, network failure), our engine will:

1. Detect a registry exit status of unreachable or error
2. Look up the fallback DB for a previous response (≤ 30 days old)
3. If one exists, serve it while still surfacing the registry failure
4. If none exists, return the failure directly

Stale data is only served when the registry cannot be reached at all.

1
Client request
2
│
3
├→ Check `fresh-cache`
4
│
5
├→ Entry exists? → Yes → Return fresh result
6
│
7
└→ No → Query registry
8
         │
9
         ├→ Registry responsive? → Yes → Return real-time result + store in cache
10
         │
11
         └→ No → Check `stale-cache`
12
                  │
13
                  ├→ Entry exists? → Yes → Return stale result
14
                  │
15
                  └→ No → Return error to client

Real-time registry calls

Whenever Redis does not contain a usable entry, our engine queries the registry in real time.

If the call succeeds (registry exit status is responsive):

• the result is returned immediately
• source.origin = "registry"
• the response is stored in the our cache layers

If the call fails (registry exit status is unreachable or error):

• our engine attempts a fallback lookup in the stale-cache
• if a stale entry exists, it is returned with source.origin = "stale-cache"
• if no stale entry exists, the error is returned directly to the client

process.sources[] and freshness reporting

For every registry queried, the API returns an entry in process.sources[]. For each entry, the origin field indicates whether the data is fresh (registry), cached but still valid (fresh-cache), or stale (stale-cache). The registryStatus field indicates whether the registry was responsive, unreachable, or skipped due to a cache hit.

In any case, the observedAt field indicates when the registry was last contacted (for registry origin) or when the cached data was originally observed (for fresh-cache and stale-cache origins). This allows you to understand the age of the data regardless of its source.

VerifyVAT never silently replaces fresh data with stale data. origin makes the source unambiguous. For how freshness signals interact with verification outcomes, see Verify an ID.

What happens when registries update upstream

Registry cycles differ (daily, weekly, monthly). Our engine doesn't always reflect these changes immediately.

Because all registry responses are cached for 24 hours, upstream changes may not appear until the cache entry expires. For example, if a registry updates at 09:00 but your entry was cached at 08:55, you will continue to see the older result until 08:55 the next day.

The 24-hour TTL is intentional. Predictable behaviour is prioritised over reacting to upstream micro-updates.