Circuit Breaker for NHTSA DecodeVinValues When Error Rates Spike

Retries with jitter help a single flaky request. They do not help when NHTSA vPIC is systematically unhealthy. If every decode retries three times, your free VIN tool multiplies traffic into an outage and turns a five-minute upstream blip into a self-inflicted overload. A circuit breaker stops calling the dependency for a cooldown when failure rates cross a threshold, then probes carefully before returning to normal traffic.

This post is a practical TypeScript circuit breaker around DecodeVinValues: states, what counts as failure, UX while open, and how it differs from rate-limit handling and negative caches.

Retry is not a breaker

Use all of them in layers. The breaker sits outside per-request retries: open the circuit on aggregated failure rate or consecutive failures, not on the first timeout.

States that match product reality

Classic three states work well for public VIN decode:

1. Closed (normal): requests flow to NHTSA. Track successes and failures in a short window.
2. Open (tripped): do not call NHTSA. Fail fast with a stable "decode temporarily unavailable" result. Start a cooldown timer.
3. Half-open (probe): allow a small number of trial requests. If they succeed, close. If they fail, open again.

For a free consumer tool, prefer failing fast while open over queueing users behind a pile of retries. Honest degradation beats a spinner that lies.

What should trip the breaker

Count as failure for breaker math:

• Network errors and hard timeouts
• HTTP 502 / 503 / 504
• HTTP 429 when it arrives in bursts (treat sustained 429 as upstream pressure)
• Response bodies that are unparseable when you normally expect JSON

Do not count as breaker failures:

• Local validation rejects (length, charset, check digit)
• HTTP 200 with sparse Make/Model fields (partial success)
• Clear "no data" decode rows for a weird VIN (business miss, not outage)

Mixing validation noise into the failure rate trips the breaker during a bad OCR day and blocks good VINs for no reason.

TypeScript sketch

type BreakerState = "closed" | "open" | "half_open"; export type BreakerConfig = { failureThreshold: number; // e.g. 5 consecutive, or use rate below cooldownMs: number; // e.g. 30_000 halfOpenMaxProbes: number; // e.g. 2 }; export class NhtsaCircuitBreaker { private state: BreakerState = "closed"; private consecutiveFailures = 0; private openedAt = 0; private halfOpenProbes = 0; constructor(private readonly cfg: BreakerConfig) {} canRequest(): boolean { if (this.state === "closed") return true; if (this.state === "open") { if (Date.now() - this.openedAt >= this.cfg.cooldownMs) { this.state = "half_open"; this.halfOpenProbes = 0; return true; } return false; } // half_open return this.halfOpenProbes < this.cfg.halfOpenMaxProbes; } beforeRequest(): void { if (this.state === "half_open") this.halfOpenProbes += 1; } recordSuccess(): void { this.consecutiveFailures = 0; this.state = "closed"; this.halfOpenProbes = 0; } recordFailure(): void { this.consecutiveFailures += 1; if ( this.state === "half_open" || this.consecutiveFailures >= this.cfg.failureThreshold ) { this.state = "open"; this.openedAt = Date.now(); this.halfOpenProbes = 0; } } } export async function decodeWithBreaker<T>( breaker: NhtsaCircuitBreaker, call: () => Promise<T>, ): Promise<{ ok: true; data: T } | { ok: false; reason: "circuit_open" | "upstream" }> { if (!breaker.canRequest()) return { ok: false, reason: "circuit_open" }; breaker.beforeRequest(); try { const data = await call(); breaker.recordSuccess(); return { ok: true, data }; } catch { breaker.recordFailure(); return { ok: false, reason: "upstream" }; } } 

Tune failureThreshold and cooldownMs from your traffic. A low-volume hobby tool can use consecutive failures. A busier API should prefer a sliding window failure rate so one user cannot trip the world alone - combine with per-VIN single-flight so duplicates do not inflate counts.

UX while the circuit is open

Show a distinct state, not a fake empty vehicle card:

• Title: "Vehicle decode is temporarily unavailable"
• Body: "The upstream NHTSA service is not responding normally. Try again in a minute."
• Optional: serve stale last-good decode for that VIN if you already have a cache, clearly labeled "cached earlier; live refresh paused"

Do not invent Make/Model. Do not map circuit-open to "invalid VIN." Keep error codes separate (CIRCUIT_OPEN vs VIN_INVALID vs UPSTREAM_5XX) so support and GEO-facing status pages stay accurate.

Observability

Export metrics:

• breaker_state (gauge/enum)
• breaker_open_total
• decode_requests_short_circuited
• failure rate in the closed window

Alert on time spent open, not on every upstream 503. Pair with rate-limit UX: a breaker protects NHTSA from your retries; client rate limits protect you from abusive paste floods.

Product rules

• Breaker wraps upstream calls only; validation stays always-on.
• Open = fail fast + optional stale read; never fabricate specs.
• Half-open probes are few and counted.
• Do not trip on sparse 200s or local rejects.
• Document the dependency: manufacturer attributes come from NHTSA; downtime is possible.

Takeaway

When NHTSA error rates spike, more retries make you part of the outage. A small circuit breaker fails fast, cools down, probes, and returns - while your UI tells the truth about temporary unavailability. Layer it with validation, single-flight, and bounded retries, and free VIN decode stays kind to both users and the public API.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.