Caching

How Vatly caches validation results

Caching

Vatly caches validation results to reduce load on upstream services (VIES and HMRC) and speed up repeat lookups.

How it works

• TTL: Validation results are cached for 24 hours
• Cache key: The combination of the VAT number and the requester VAT number (if provided)
• Storage: Cached in the database alongside fresh results

Detecting cached responses

When a result comes from cache, two fields appear in the meta object:

{
  "data": { "..." },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "cached": true,
    "cached_at": "2026-03-06T10:00:00Z"
  }
}

Field	Value	Meaning
meta.cached	true	Result served from cache
meta.cached	false	Fresh result from VIES/HMRC
meta.cached_at	ISO 8601 timestamp	When the cached result was originally fetched

Usage counting

Cached responses still count toward your monthly quota. This is because caching is a performance optimization, not a billing bypass. Check your remaining quota via the X-RateLimit-Remaining header on each response.

Stale cache fallback

When an upstream service (VIES or HMRC) is down and no fresh cache exists (within the 24-hour TTL), Vatly falls back to the most recent cached result for that VAT number, regardless of age.

The response includes meta.stale: true so you know the data may be outdated:

{
  "data": { "..." },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "cached": true,
    "cached_at": "2026-03-01T10:00:00Z",
    "stale": true
  }
}

Scenario	meta.cached	meta.stale
Fresh cache hit (within 24h TTL)	true	not present
Stale fallback (beyond TTL, upstream down)	true	true
Fresh upstream result	false	not present

Stale results still count toward your monthly quota. If no cached result exists at all for the requested VAT number, the API returns a 503 error as usual.

Cache invalidation

There is no manual cache invalidation. After the 24-hour TTL expires, the next request for that VAT number will fetch a fresh result from the upstream service.