Context
VIES, the EU's official VAT-validation service, is free — and unreliable enough per member state that a thin passthrough to it isn't a product a business can depend on for compliance-critical checks like reverse-charge validation on every invoice.
The problem
Two requirements pull in different directions. The service has to keep answering VAT checks through a VIES outage, and every answer still has to be provably correct enough to hold up if a tax authority asks for evidence later. Solving only the first with a naive cache produces answers with no provenance; solving only the second with a strict passthrough means an outage in Brussels takes down validation everywhere.
What we built
Per-country circuit breaking, not one global dependency. VIES isn't one
system from an availability standpoint — it's 27 independent national
endpoints behind a shared interface. Treating them as one dependency means one
member state's outage takes out validation for every country's VAT numbers.
A circuit breaker per member state trips open after three consecutive
failures, gates recovery behind a cooldown, and serves the last known-good
response — clearly labelled as cached — while open. A ?live=true path exists
as an explicit, separately-priced bypass for callers who need a
compliance-grade check regardless of cache state.
A canonical identifier across incompatible national data. Company registry ingestion runs as scheduled per-country ETL jobs — VIES on demand, UK Companies House daily, French INSEE Sirene weekly, Romanian ONRC monthly, with further country adapters at varying stages of coverage — each resolving into one canonical ID derived from a hash of country and registration number, so the same company sourced from two different registries lands on one row instead of a duplicate. Ingestion failures route to a dead-letter table rather than failing the whole job, and distributed locks stop overlapping runs from double-processing a source.
Billing isolated as its own failure domain. Billing runs as a separate service with its own database access and its own Stripe integration. The core API never talks to Stripe directly, and the browser never talks to billing directly either — every path routes through an internally authenticated call. The isolation means a billing-provider outage degrades checkout, not the VAT validation the product actually sells.
Platform engineering decisions worth naming
Scope discipline on day one. The first version deliberately ingested one country's registry rather than two at once, on the reasoning that ingesting two national registries simultaneously was the single biggest schedule risk in the initial build — get the canonical-identifier model right against one source before asking it to reconcile two.
No SLA claims the architecture doesn't back up. Uptime is scoped explicitly to what the service itself controls, kept separate from VIES's own upstream availability, rather than one blended number with no load-test evidence behind it.
Outcome
VAT validation now degrades gracefully through VIES outages instead of propagating them, company data resolves to one stable identity across incompatible national sources, and billing failures stay contained to billing — see Company Intel.
Lessons learned
Model an upstream dependency at the granularity it actually fails at. Treating 27 national endpoints as one dependency means every outage is a full outage; circuit-breaking per country contains the blast radius to the country that's actually down.
A canonical identifier is a data-modeling decision, not an implementation detail. Deciding how records from incompatible sources reconcile into one identity has to happen before ingestion scales past one source, not after.
Isolate the failure domain that isn't your core product. Billing matters, but it isn't what a compliance API sells — keeping it as a separately deployable service means its outages don't become the core product's outages.