DEV Community: Vin Lookup

Shadowing Live VIN Decodes Against a Canary Path Without Double-Billing Users

Vin Lookup — Thu, 15 Oct 2026 08:41:06 +0000

A free VIN decode edge that ships a new DecodeVinValues parser, cache key, or upstream client wants proof in production without making users wait on two live calls -- or burning NHTSA quota twice per paste. Hedged requests (covered elsewhere) race parallel attempts for latency. Singleflight (elsewhere) merges identical in-flight VINs. Concurrency limits (elsewhere) cap sockets. This post is different: shadow (dark) traffic -- the user-facing path stays primary; a canary path runs in the background on a sample of requests; differences are logged; the user is never billed twice in time or in invented "premium canary" product framing.

The goal is narrow: compare primary vs canary decode outcomes safely, keep the primary response authoritative for the UI, and never double-charge the user experience (or imply a paid dual-decode) while you validate a change. Shadow traffic is a release-safety tool: it answers "does the canary disagree?" without turning every paste into two user-visible decodes.

Shadow vs hedge, singleflight, concurrency

Hedge -- start a second live attempt to win latency; one result serves the user
Singleflight -- share one in-flight promise per VIN key
Concurrency limit -- bound simultaneous upstream sockets
Shadow -- primary serves the user; canary runs async on a sample; results compared offline; canary must not block or replace the user response unless you explicitly promote it

Shadow is for correctness confidence, not for making the happy path faster. If the canary also calls live NHTSA, sample aggressively and prefer replaying cached primary bodies into the canary parser when the change is parser-only.

Sample, fork, compare

Serve primary first. Optionally enqueue a shadow job keyed by request id. Cap shadow concurrency separately so canaries cannot starve primary. Compare field-level diffs without inventing missing catalog values to "align" sides.

export type DecodeBody = { raw: string; fields: Record<string, string> };

export type ShadowDiff = {
  requestId: string;
  vinNormalized: string;
  mismatchedKeys: string[];
  primaryOnly: string[];
  canaryOnly: string[];
};

export type PrimaryDecode = (vin: string) => Promise<DecodeBody>;
export type CanaryDecode = (vin: string, primary: DecodeBody) => Promise<DecodeBody>;

export type ShadowGate = {
  sampleRate: number; // 0..1
  maxShadowInFlight: number;
  shadowInFlight: number;
};

export function shouldShadow(gate: ShadowGate, requestId: string): boolean {
  if (gate.shadowInFlight >= gate.maxShadowInFlight) return false;
  let h = 0;
  for (let i = 0; i < requestId.length; i++) {
    h = (Math.imul(31, h) + requestId.charCodeAt(i)) | 0;
  }
  const unit = ((h >>> 0) % 10_000) / 10_000;
  return unit < gate.sampleRate;
}

export function diffFields(
  primary: DecodeBody,
  canary: DecodeBody,
  requestId: string,
  vinNormalized: string,
): ShadowDiff {
  const pk = new Set(Object.keys(primary.fields));
  const ck = new Set(Object.keys(canary.fields));
  const mismatchedKeys: string[] = [];
  for (const k of pk) {
    if (ck.has(k) && primary.fields[k] !== canary.fields[k]) {
      mismatchedKeys.push(k);
    }
  }
  return {
    requestId,
    vinNormalized,
    mismatchedKeys,
    primaryOnly: [...pk].filter((k) => !ck.has(k)),
    canaryOnly: [...ck].filter((k) => !pk.has(k)),
  };
}

export async function decodeWithShadow(
  vinNormalized: string,
  requestId: string,
  primaryFn: PrimaryDecode,
  canaryFn: CanaryDecode,
  gate: ShadowGate,
  onDiff: (d: ShadowDiff) => void,
): Promise<DecodeBody> {
  const primary = await primaryFn(vinNormalized);

  if (shouldShadow(gate, requestId)) {
    gate.shadowInFlight += 1;
    void (async () => {
      try {
        const canary = await canaryFn(vinNormalized, primary);
        onDiff(diffFields(primary, canary, requestId, vinNormalized));
      } catch {
        // Shadow failures must not affect the user path
      } finally {
        gate.shadowInFlight -= 1;
      }
    })();
  }

  return primary; // always authoritative for the UI
}

export function userFacingNote(): string {
  return "Decoded via primary path -- canary shadow does not change this card";
}

Prefer parser-only canaries that reuse primary.raw so you do not double-hit NHTSA. When the canary must call live, keep sampleRate tiny and count canary calls against a separate concurrency/retry budget. Record shadow metrics (sampled, skipped by gate, diff count, canary error count) so you can raise or lower sampling without guessing. If diffs cluster on one field mapper, fix that mapper -- do not paper over disagreement by copying primary values into the canary result.

Forbidden upgrades

Blocking the user response on canary completion ("wait for both to be sure")
Replacing primary fields with canary fields silently when they differ
Inventing catalog values to make primary and canary "match" in diffs
Labeling the UI "dual verified decode" or implying a paid double lookup
Letting shadow traffic ignore concurrency / retry budgets and stampede NHTSA

Refuse those. Shadow is observability, not a second product SKU and not a license to invent specs.

Quick checks

import assert from "node:assert/strict";

const gate: ShadowGate = {
  sampleRate: 1,
  maxShadowInFlight: 2,
  shadowInFlight: 0,
};
let primaryCalls = 0;
let canaryCalls = 0;
const diffs: ShadowDiff[] = [];

const primaryFn: PrimaryDecode = async () => {
  primaryCalls += 1;
  return { raw: "{}", fields: { Make: "HONDA", Model: "Accord" } };
};
const canaryFn: CanaryDecode = async (_vin, primary) => {
  canaryCalls += 1;
  return {
    raw: primary.raw,
    fields: { Make: "HONDA", Model: "Civic" }, // intentional mismatch
  };
};

const body = await decodeWithShadow(
  "1HGCM82633A004352",
  "req-shadow-1",
  primaryFn,
  canaryFn,
  gate,
  (d) => diffs.push(d),
);
assert.equal(body.fields.Model, "Accord"); // primary wins
assert.equal(primaryCalls, 1);
await new Promise((r) => setTimeout(r, 20));
assert.equal(canaryCalls, 1);
assert.ok(diffs[0]?.mismatchedKeys.includes("Model"));
assert.ok(/primary path/i.test(userFacingNote()));
assert.ok(!/dual verified|premium canary/i.test(userFacingNote()));

Review rule: shadow modules must return primary to users and must not invent fields to force canary agreement.

Takeaway

Shadow traffic lets you validate DecodeVinValues changes against a canary path while the primary response stays authoritative. Sample, isolate concurrency, prefer replaying primary bodies into parser canaries, and log diffs without blocking users or double-billing their experience. Promote the canary only after diffs look boring -- never mid-request. Your free VIN edge stays honest when canaries illuminate disagreements -- without inventing catalog marketing or implying a paid dual decode.

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

Warming a VIN Decode Cache for Popular Makes Without Inventing Spec Completeness

Vin Lookup — Wed, 14 Oct 2026 09:20:24 +0000

A free VIN decode that always hits live NHTSA DecodeVinValues on every paste pays cold-start latency for makes you already decode often. ETag revalidation and quota headers are covered elsewhere. This post is different: warm a small cache of successful decode bodies for popular make patterns before peak traffic, label every hit as cached, and never invent missing catalog rows to make a warmed card look complete.

The goal is honest pre-fetch: store only bodies you actually received from vPIC, bound the warm set so you do not hammer upstream, and refuse folklore fills when a warmed entry lacks a field.

Warm cache vs other cache tools

Use make-pattern warmup when:

You already see a stable set of popular Makes (or Make+ModelYear buckets) in traffic
You can schedule a bounded pre-fetch of real DecodeVinValues responses you are allowed to store
Interactive UI can disclose "cached decode" vs "live decode"

Do not use warmup to:

Fabricate Make/Model/Year/spec rows for VINs you never decoded
Bypass ETag / If-None-Match when you already have a fresh body for that VIN
Ignore upstream rate-limit headers while filling the warm set
Pretend a warmed partial body is a complete safety or options package

If the warm set has no entry for a VIN, call live decode or show loading -- do not invent rows so the card looks full.

Bound the warm set

Key by normalized VIN. Store only successful vPIC bodies. Cap how many VINs you warm per make and how often the job runs.

export type WarmEntry = {
  vinNormalized: string;
  make: string;
  body: Record<string, string | null>;
  fetchedAt: number; // epoch ms of live DecodeVinValues success
  source: "vpic";
};

export type WarmStore = Map<string, WarmEntry>;

export type WarmPlan = {
  make: string;
  vins: string[]; // already normalized, capped
  maxPerMake: number;
};

export function planWarmup(
  popularMakes: { make: string; sampleVins: string[] }[],
  maxPerMake = 25,
): WarmPlan[] {
  return popularMakes.map(({ make, sampleVins }) => ({
    make,
    maxPerMake,
    vins: sampleVins.slice(0, maxPerMake),
  }));
}

export async function runWarmup(
  store: WarmStore,
  plans: WarmPlan[],
  decodeLive: (vin: string) => Promise<Record<string, string | null>>,
  sleepMs: (ms: number) => Promise<void>,
  gapMs = 250,
): Promise<{ warmed: number; skipped: number }> {
  let warmed = 0;
  let skipped = 0;
  for (const plan of plans) {
    for (const vin of plan.vins) {
      if (store.has(vin)) {
        skipped += 1;
        continue;
      }
      const body = await decodeLive(vin);
      store.set(vin, {
        vinNormalized: vin,
        make: plan.make,
        body: { ...body },
        fetchedAt: Date.now(),
        source: "vpic",
      });
      warmed += 1;
      await sleepMs(gapMs);
    }
  }
  return { warmed, skipped };
}

Space calls with gapMs and respect any upstream quota path you already run. Warmup is not a license to burst past NHTSA limits.

Serve warmed hits with disclosure

A warm hit is still a prior live decode -- not a guarantee that every catalog field is present, and not permission to fill blanks.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type DecodeServe = {
  body: Record<string, string | null>;
  source: "warm-cache" | "live";
  fetchedAt: number;
};

export function serveDecode(
  store: WarmStore,
  vinNormalized: string,
  live: DecodeServe | null,
): DecodeServe | null {
  if (live) return live;
  const hit = store.get(vinNormalized);
  if (!hit) return null;
  return {
    body: { ...hit.body },
    source: "warm-cache",
    fetchedAt: hit.fetchedAt,
  };
}

export function fieldOrMissing(
  body: Record<string, string | null>,
  key: string,
): string {
  const raw = (body[key] ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return "not provided";
  }
  return raw;
}

export function assertNoWarmInvent(moduleSource: string): void {
  const banned = [
    /spec.?complete/i,
    /full.?options.?package/i,
    /invent(?:ed|ing)?\s+catalog/i,
    /folklore.?fill/i,
    /assumed.?standard/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `Warm-cache module must not invent spec completeness: ${re}`,
      );
    }
  }
}

UI copy should say the decode came from warm cache when source === "warm-cache", including fetchedAt. Missing keys stay "not provided" -- never "assumed Standard for this make."

Forbidden upgrades

Product pressure often asks for:

Filling blank catalog fields from Make averages so warmed cards look "complete"
Warming fabricated VINs or synthetic bodies you never received from vPIC
Skipping rate gaps and quota handling during the warm job
Labeling a warm hit as a fresh live decode
Treating a warm hit as proof that every safety option is present

Refuse those. Completeness is whatever vPIC returned on that VIN -- not what marketing expects for the make.

Quick checks

import assert from "node:assert/strict";

const store: WarmStore = new Map();
const plans = planWarmup(
  [{ make: "TOYOTA", sampleVins: ["VIN1", "VIN2", "VIN3"] }],
  2,
);
assert.equal(plans[0].vins.length, 2);

const fakeLive = async (vin: string) => ({
  Make: "TOYOTA",
  Model: vin === "VIN1" ? "Camry" : "",
  ABS: "",
});

await runWarmup(store, plans, fakeLive, async () => {}, 0);
assert.equal(store.size, 2);

const served = serveDecode(store, "VIN1", null);
assert.equal(served?.source, "warm-cache");
assert.equal(fieldOrMissing(served!.body, "Make"), "TOYOTA");
assert.equal(fieldOrMissing(served!.body, "ABS"), "not provided");
assert.ok(!/assumed|complete|standard for make/i.test(
  fieldOrMissing(served!.body, "ABS"),
));

assert.equal(serveDecode(store, "UNKNOWN", null), null);

Review rule: warm-cache modules must not invent catalog completeness phrases except in forbidding tests. Never upgrade a blank field because the make is popular.

UI copy that stays honest

Prefer "Showing cached decode from warm set (fetched …)" and keep blank fields as "not provided" even for popular Makes. Avoid "Full specs for this make -- preloaded," "Assumed Standard for Toyota," or relabeling a warm hit as a live DecodeVinValues response.

Takeaway

Warming a VIN decode cache for popular makes is a latency tool, not a completeness tool. Store only real vPIC bodies, bound the job, disclose cache hits, and leave empty fields as "not provided." Your free VIN UI stays trustworthy when a warm hit is a dated prior decode -- never a folklore-filled "full spec" card.

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

Pooling HTTP Connections to NHTSA Without Starving VIN Decode Workers

Vin Lookup — Wed, 14 Oct 2026 09:01:53 +0000

A free VIN decode edge that opens a fresh TCP/TLS session for every DecodeVinValues call pays handshake latency on every paste. One giant shared agent with unlimited sockets can starve other workers when NHTSA slows. Concurrency semaphores (covered elsewhere) cap logical in-flight decodes. Token buckets (elsewhere) shape start rate. Circuit breakers (elsewhere) stop calling an unhealthy dependency. This post is different: HTTP connection pooling / keep-alive limits -- reuse warm connections to NHTSA, bound pool size and wait time, and fail honestly when the pool is exhausted instead of inventing decode specs while sockets pile up.

The goal is narrow: configure a keep-alive pool for upstream DecodeVinValues, size it so workers are not starved, and surface pool-wait timeouts without fake catalog cards. Pooling is a transport concern: it does not replace app-level concurrency caps, and it must not become an unbounded socket factory under load.

Connection pool vs concurrency, token bucket, circuit breaker

Concurrency semaphore -- how many decode operations may run at once (app logic)
Token bucket -- how many starts per second you allow
Circuit breaker -- whether to refuse upstream calls after error spikes
Connection pool -- how many TCP/TLS connections may be open/idle/waiting toward NHTSA

You can have free semaphore slots and still block on a saturated pool -- or a huge pool that opens more sockets than NHTSA or your process can handle. Size the pool to match (or sit slightly under) your concurrency cap.

Shape the pool

Use a shared undici/fetch Agent (or equivalent) with bounded connections, bounded pending, and keep-alive. Acquire implicitly on each upstream call; treat pool timeouts as retryable infrastructure errors, not as successful empty decodes.

import { Agent, request } from "undici";

export type PoolConfig = {
  connections: number; // max open sockets toward NHTSA
  pipelining: number;
  keepAliveTimeout: number; // ms
  keepAliveMaxTimeout: number;
  connectTimeout: number;
  bodyTimeout: number;
  headersTimeout: number;
};

export function createNhtsaAgent(cfg: PoolConfig): Agent {
  return new Agent({
    connections: cfg.connections,
    pipelining: cfg.pipelining,
    keepAliveTimeout: cfg.keepAliveTimeout,
    keepAliveMaxTimeout: cfg.keepAliveMaxTimeout,
    connect: { timeout: cfg.connectTimeout },
    bodyTimeout: cfg.bodyTimeout,
    headersTimeout: cfg.headersTimeout,
  });
}

export type UpstreamResult =
  | { ok: true; status: number; body: string }
  | { ok: false; reason: "pool-timeout" | "upstream-error"; detail: string };

export async function decodeVinValuesPooled(
  agent: Agent,
  vinNormalized: string,
  baseUrl = "https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues",
): Promise<UpstreamResult> {
  const url = `${baseUrl}/${encodeURIComponent(vinNormalized)}?format=json`;
  try {
    const res = await request(url, {
      method: "GET",
      dispatcher: agent,
      headersTimeout: 5_000,
      bodyTimeout: 10_000,
    });
    const body = await res.body.text();
    if (res.statusCode >= 500) {
      return {
        ok: false,
        reason: "upstream-error",
        detail: `status ${res.statusCode}`,
      };
    }
    return { ok: true, status: res.statusCode, body };
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    // undici surfaces connect/pool waits as errors -- treat as infra, not specs
    if (/timeout|connect|pool|network/i.test(msg)) {
      return { ok: false, reason: "pool-timeout", detail: msg };
    }
    return { ok: false, reason: "upstream-error", detail: msg };
  }
}

export function poolFailureMessage(r: Extract<UpstreamResult, { ok: false }>): string {
  return r.reason === "pool-timeout"
    ? "Decode busy: connection pool wait timed out -- try again shortly"
    : "Decode failed talking to NHTSA -- try again later";
}

Pair connections with your concurrency semaphore (e.g. both 8). If semaphore is 32 and pool is 2, workers queue on sockets and look "stuck." If pool is 100 and semaphore is 8, you waste file descriptors. Watch pending-acquire counts: a rising pending queue with flat successful decodes usually means the pool is undersized relative to concurrency -- or NHTSA is slow enough that warm sockets never return in time. Prefer failing a single request with pool-timeout over letting every worker block indefinitely on socket checkout.

Sizing without starvation

Prefer:

Pool size â‰ˆ concurrency cap for the NHTSA host
Short connect/headers timeouts so wedged sockets free workers
Keep-alive so warm sockets serve repeat pastes cheaply
Honest pool-timeout messages -- never invent Make/Model/Year
Metrics: active, pending, timeouts -- tune from data

Avoid unlimited agents "for speed" and avoid serializing all traffic onto one socket when concurrency expects parallelism.

Forbidden upgrades

Opening a new TLS session per VIN while claiming you "pool"
Returning folklore catalog rows when pool-timeout fires
Setting connections far above the concurrency semaphore so sockets starve the process
Disabling keep-alive to "simplify" and accepting handshake storms
Treating pool wait as success with an empty Results array

Refuse those. A bounded warm pool is infrastructure honesty, not a place to fake specs.

Quick checks

import assert from "node:assert/strict";

const cfg: PoolConfig = {
  connections: 2,
  pipelining: 1,
  keepAliveTimeout: 10_000,
  keepAliveMaxTimeout: 30_000,
  connectTimeout: 2_000,
  bodyTimeout: 5_000,
  headersTimeout: 5_000,
};
assert.equal(cfg.connections, 2);
assert.ok(cfg.keepAliveTimeout > 0);

const fail: UpstreamResult = {
  ok: false,
  reason: "pool-timeout",
  detail: "Connect Timeout Error",
};
assert.ok(/connection pool wait/i.test(poolFailureMessage(fail)));
assert.ok(!/Make|ModelYear|invented/i.test(poolFailureMessage(fail)));

// Documented invariant: pool connections should not greatly exceed app concurrency
const appConcurrency = 8;
assert.ok(cfg.connections <= appConcurrency);

Review rule: pool modules must bound sockets toward NHTSA and must not invent decode bodies on pool timeout.

Takeaway

HTTP connection pooling keeps DecodeVinValues warm without handshake storms, but an oversized or undersized pool can starve workers just as badly as no pool at all. Match pool size to concurrency, keep timeouts tight, reuse keep-alive sockets, and fail with honest busy messages when the pool cannot grant a connection. Tune from metrics, not folklore. Your free VIN edge stays calm when sockets are bounded infrastructure -- never a backdoor for invented catalog marketing.

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

Honoring Upstream Rate-Limit Headers When Retrying VIN Decodes Against NHTSA

Vin Lookup — Wed, 14 Oct 2026 08:43:34 +0000

A free VIN decode that retries NHTSA DecodeVinValues after a 429 already needs jittered backoff and a client token bucket. Those are local policies. Upstream often also returns rate-limit quota headers that tell you how many calls remain and when the window resets. Ignoring them and retrying on your own schedule burns the shared courtesy quota and turns a soft throttle into a hard block.

This post is narrower than Retry-After-only parsers and narrower than client token buckets: read RateLimit-* / X-RateLimit-* (and Retry-After when present), decide whether a retry is still allowed, and wait until the reset window -- without inventing a successful decode card while you wait.

Why quota headers beat guessing

Client token buckets answer "how many calls may leave this process?" Jittered backoff answers "when peers fail together, scatter wake-ups." Neither reads what the server said about remaining budget.

Common headers on public APIs and reverse proxies:

RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset (IETF draft style)
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (legacy)
Retry-After on 429 / 503 (seconds or HTTP-date)

If Remaining is 0 and Reset is thirty seconds out, sleeping 200ms of jitter and firing again is rude. Prefer the upstream clock.

Parse remaining and reset first

Normalize header names case-insensitively. Prefer IETF RateLimit-* when both families appear. Treat missing headers as "unknown," not as infinite quota.

export type QuotaSnapshot = {
  limit: number | null;
  remaining: number | null;
  resetAtMs: number | null;
  retryAfterMs: number | null;
  source: "ratelimit" | "x-ratelimit" | "retry-after-only" | "none";
};

function header(
  headers: Headers,
  name: string,
): string | null {
  return headers.get(name);
}

function parseIntHeader(raw: string | null): number | null {
  if (raw == null || !/^\d+$/.test(raw.trim())) return null;
  const n = Number(raw.trim());
  return Number.isFinite(n) ? n : null;
}

function parseReset(
  raw: string | null,
  nowMs: number,
): number | null {
  if (raw == null) return null;
  const t = raw.trim();
  if (/^\d+$/.test(t)) {
    const n = Number(t);
    // Unix seconds if large; else delta seconds
    if (n > 1_000_000_000) return n * 1000;
    return nowMs + n * 1000;
  }
  const when = Date.parse(t);
  return Number.isNaN(when) ? null : when;
}

export function readQuotaHeaders(
  headers: Headers,
  nowMs: number = Date.now(),
): QuotaSnapshot {
  const ietfLimit = parseIntHeader(header(headers, "RateLimit-Limit"));
  const ietfRem = parseIntHeader(header(headers, "RateLimit-Remaining"));
  const ietfReset = parseReset(header(headers, "RateLimit-Reset"), nowMs);

  const xLimit = parseIntHeader(header(headers, "X-RateLimit-Limit"));
  const xRem = parseIntHeader(header(headers, "X-RateLimit-Remaining"));
  const xReset = parseReset(header(headers, "X-RateLimit-Reset"), nowMs);

  const retryRaw = header(headers, "Retry-After");
  let retryAfterMs: number | null = null;
  if (retryRaw) {
    const t = retryRaw.trim();
    if (/^\d+$/.test(t)) retryAfterMs = Number(t) * 1000;
    else {
      const when = Date.parse(t);
      if (!Number.isNaN(when)) retryAfterMs = Math.max(0, when - nowMs);
    }
  }

  if (ietfRem != null || ietfReset != null || ietfLimit != null) {
    return {
      limit: ietfLimit,
      remaining: ietfRem,
      resetAtMs: ietfReset,
      retryAfterMs,
      source: "ratelimit",
    };
  }
  if (xRem != null || xReset != null || xLimit != null) {
    return {
      limit: xLimit,
      remaining: xRem,
      resetAtMs: xReset,
      retryAfterMs,
      source: "x-ratelimit",
    };
  }
  if (retryAfterMs != null) {
    return {
      limit: null,
      remaining: null,
      resetAtMs: null,
      retryAfterMs,
      source: "retry-after-only",
    };
  }
  return {
    limit: null,
    remaining: null,
    resetAtMs: null,
    retryAfterMs: null,
    source: "none",
  };
}

Gate retries on remaining, not only status

A 200 with RateLimit-Remaining: 0 is a hint to pause before the next paste. A 429 with Remaining still positive may be a proxy quirk -- still honor Retry-After when present.

const MAX_WAIT_MS = 60_000;
const MIN_WAIT_MS = 250;

export type RetryPlan =
  | { action: "proceed" }
  | { action: "wait"; waitMs: number; reason: string }
  | { action: "refuse"; reason: string };

export function planDecodeRetry(
  status: number,
  quota: QuotaSnapshot,
  nowMs: number = Date.now(),
): RetryPlan {
  if (status === 200 && (quota.remaining == null || quota.remaining > 0)) {
    return { action: "proceed" };
  }

  const waits: number[] = [];
  if (quota.retryAfterMs != null) waits.push(quota.retryAfterMs);
  if (quota.resetAtMs != null) waits.push(Math.max(0, quota.resetAtMs - nowMs));
  if (quota.remaining === 0 && waits.length === 0) {
    return {
      action: "refuse",
      reason: "rate-limit remaining is 0 without a reset hint",
    };
  }

  if (status === 429 || status === 503 || quota.remaining === 0) {
    if (waits.length === 0) {
      return {
        action: "refuse",
        reason: "throttled without Retry-After or reset",
      };
    }
    const waitMs = Math.min(
      MAX_WAIT_MS,
      Math.max(MIN_WAIT_MS, Math.max(...waits)),
    );
    return {
      action: "wait",
      waitMs,
      reason: `upstream quota headers source=${quota.source}`,
    };
  }

  return { action: "proceed" };
}

Do not invent catalog rows while waiting. Surface "NHTSA asked us to wait" or a disabled decode button -- never a fake Make/Model card.

What this is not

Not a client token bucket (local admit rate before the call leaves)
Not decorrelated jitter (scatter after a transient failure when headers are absent)
Not circuit-breaker metrics (open/half-open gauges)
Not a license to retry sparse 200s with empty ADAS fields

Sparse successful decodes are successes. Quota headers guide when the next call may leave, not whether blank PedestrianAutomaticEmergencyBraking should be re-fetched.

Quick checks

import assert from "node:assert/strict";

const h = new Headers({
  "RateLimit-Limit": "100",
  "RateLimit-Remaining": "0",
  "RateLimit-Reset": "30",
  "Retry-After": "30",
});
const q = readQuotaHeaders(h, 1_000_000);
assert.equal(q.source, "ratelimit");
assert.equal(q.remaining, 0);
assert.equal(q.retryAfterMs, 30_000);

const plan = planDecodeRetry(429, q, 1_000_000);
assert.equal(plan.action, "wait");
if (plan.action === "wait") {
  assert.ok(plan.waitMs >= 250 && plan.waitMs <= 60_000);
}

const ok = planDecodeRetry(
  200,
  readQuotaHeaders(new Headers({ "RateLimit-Remaining": "12" })),
);
assert.equal(ok.action, "proceed");

Takeaway

When retrying VIN decodes against NHTSA, honor upstream rate-limit headers: parse Remaining/Reset/Retry-After, wait for the reset window, and refuse to stampede when Remaining is zero without a hint. Keep local token buckets and jitter for budgets and peer scatter -- they do not replace reading what the server already told you. Your free decode stays polite when quota headers drive the wait and empty cards stay empty until a real response arrives.

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

Adapting VIN Decode Timeouts from Recent NHTSA Latency Percentiles

Vin Lookup — Tue, 13 Oct 2026 09:22:25 +0000

A free VIN edge that hard-codes one upstream timeout forever either cuts off healthy DecodeVinValues calls during a quiet hour or waits too long when NHTSA p95 has already climbed. Static budget splits (client / edge / upstream slices of one UX deadline) are covered elsewhere. Circuit half-open probes and deadline propagation are separate tools. This post is about adapting the Next upstream wait from recent observed latency percentiles -- not inventing a new flat constant every deploy.

The goal is honest timing: raise or lower the DecodeVinValues timeout from a rolling p50/p95 window, clamp to safe floors and ceilings, and never treat a percentile guess as proof that NHTSA is "fast today" for marketing copy.

Adaptive timeout vs static budget split

Concern	Static budget (#143-style)	Adaptive percentile timeout
Input	One UX deadline minted at submit	Rolling latency samples from recent upstream calls
Output	Nested client / edge / upstream slices	A single next-upstream `timeoutMs` (then nest budgets as usual)
Changes when	Rarely (config / deploy)	After enough samples in the window
Failure if misused	Orphaned hops when slices drift	Thrashing timeouts from tiny sample sets

Use adaptive timeouts when you already record successful and timed-out DecodeVinValues durations. Keep the static nest for how much of the UX deadline each hop may consume. Adaptation only proposes the upstream slice (or a multiplier on it) -- it does not replace AbortSignal propagation or half-open probes.

Record samples, compute percentiles, clamp

Keep a ring buffer of recent upstream durations (success and timeout). Require a minimum sample count before adapting. Compute p50 and p95; set the next timeout to something like p95 * factor clamped between a floor (never starve healthy calls) and a ceiling (never hang the edge forever).

export type LatencySample = {
  durationMs: number;
  outcome: "ok" | "timeout" | "error";
  at: number; // epoch ms
};

export type AdaptiveTimeoutConfig = {
  windowSize: number; // max samples retained
  minSamples: number; // refuse adapt below this
  p95Factor: number; // e.g. 1.25
  floorMs: number; // e.g. 1_500
  ceilingMs: number; // e.g. 8_000
  defaultMs: number; // used until minSamples
};

export function pushSample(
  buf: LatencySample[],
  sample: LatencySample,
  windowSize: number,
): LatencySample[] {
  const next = [...buf, sample];
  if (next.length <= windowSize) return next;
  return next.slice(next.length - windowSize);
}

function percentile(sorted: number[], p: number): number {
  if (sorted.length === 0) return 0;
  const idx = Math.min(
    sorted.length - 1,
    Math.max(0, Math.ceil((p / 100) * sorted.length) - 1),
  );
  return sorted[idx]!;
}

export function suggestUpstreamTimeoutMs(
  samples: LatencySample[],
  cfg: AdaptiveTimeoutConfig,
): { timeoutMs: number; source: "default" | "p95"; p50: number | null; p95: number | null } {
  const usable = samples.filter((s) => s.outcome === "ok" || s.outcome === "timeout");
  if (usable.length < cfg.minSamples) {
    return {
      timeoutMs: cfg.defaultMs,
      source: "default",
      p50: null,
      p95: null,
    };
  }
  const durations = usable.map((s) => s.durationMs).sort((a, b) => a - b);
  const p50 = percentile(durations, 50);
  const p95 = percentile(durations, 95);
  const raw = Math.round(p95 * cfg.p95Factor);
  const timeoutMs = Math.min(cfg.ceilingMs, Math.max(cfg.floorMs, raw));
  return { timeoutMs, source: "p95", p50, p95 };
}

Do not adapt from a single slow call. Do not lower the floor so far that a normal DecodeVinValues always races the abort. Do not raise the ceiling past your edge platform's remaining time.

Wire into the next decode -- keep budgets nested

Adaptation proposes timeoutMs. Still nest it under the end-to-end UX budget: upstreamMs = min(suggested, remainingBudgetUpstreamSlice). Record the actual duration when the call settles so the next suggestion stays honest.

export async function decodeWithAdaptiveTimeout(
  vin: string,
  samples: LatencySample[],
  cfg: AdaptiveTimeoutConfig,
  remainingUpstreamBudgetMs: number,
  fetchDecode: (vin: string, timeoutMs: number) => Promise<unknown>,
): Promise<unknown> {
  const suggestion = suggestUpstreamTimeoutMs(samples, cfg);
  const timeoutMs = Math.min(suggestion.timeoutMs, remainingUpstreamBudgetMs);
  const started = Date.now();
  try {
    const body = await fetchDecode(vin, timeoutMs);
    samples.splice(
      0,
      samples.length,
      ...pushSample(
        samples,
        { durationMs: Date.now() - started, outcome: "ok", at: Date.now() },
        cfg.windowSize,
      ),
    );
    return body;
  } catch (err) {
    const durationMs = Date.now() - started;
    const outcome =
      err instanceof Error && /timeout|aborted/i.test(err.message)
        ? "timeout"
        : "error";
    samples.splice(
      0,
      samples.length,
      ...pushSample(
        samples,
        { durationMs, outcome, at: Date.now() },
        cfg.windowSize,
      ),
    );
    throw err;
  }
}

Never advertise "NHTSA is fast today" from a low p95 in product copy. Percentiles are operational inputs, not safety or catalog claims.

Forbidden upgrades

Setting timeout from one sample or from error-only samples (skews high)
Removing the floor/ceiling so adaptation can starve or hang the edge
Replacing static budget nesting with "just use p95" as the whole UX deadline
Claiming adaptive timeout proves DecodeVinValues health for users
Sharing one global adapter across unrelated upstreams without separate windows

Quick checks

import assert from "node:assert/strict";

const cfg: AdaptiveTimeoutConfig = {
  windowSize: 20,
  minSamples: 5,
  p95Factor: 1.25,
  floorMs: 1_500,
  ceilingMs: 8_000,
  defaultMs: 4_000,
};

assert.equal(suggestUpstreamTimeoutMs([], cfg).source, "default");
assert.equal(suggestUpstreamTimeoutMs([], cfg).timeoutMs, 4_000);

const samples: LatencySample[] = Array.from({ length: 8 }, (_, i) => ({
  durationMs: 1_000 + i * 100,
  outcome: "ok" as const,
  at: Date.now(),
}));
const suggested = suggestUpstreamTimeoutMs(samples, cfg);
assert.equal(suggested.source, "p95");
assert.ok(suggested.timeoutMs >= cfg.floorMs);
assert.ok(suggested.timeoutMs <= cfg.ceilingMs);
assert.ok(suggested.p95 != null && suggested.p50 != null);

const clamped = suggestUpstreamTimeoutMs(
  Array.from({ length: 8 }, () => ({
    durationMs: 20_000,
    outcome: "timeout" as const,
    at: Date.now(),
  })),
  cfg,
);
assert.equal(clamped.timeoutMs, cfg.ceilingMs);

Review rule: adaptive-timeout modules must require min samples, clamp floors/ceilings, and stay nested under the UX budget -- never replace half-open probes or static slice math with a bare percentile.

Takeaway

Adapt the Next DecodeVinValues wait from rolling latency percentiles, clamp hard, and keep static budget nesting for how slices share one deadline. Your free VIN API stays kind to users and to NHTSA when timeouts follow recent reality instead of a forgotten constant -- without inventing health grades from p95 alone.

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

Coalescing Identical In-Flight VIN Decode Requests So Duplicate Pastes Share One Upstream Call

Vin Lookup — Tue, 13 Oct 2026 09:04:55 +0000

A free VIN decode form (or thin proxy) often starts DecodeVinValues as soon as a normalized 17-character VIN is ready. Users -- and impatient front-ends -- paste the same VIN twice, double-click Decode, or remount a component that fires again while the first request is still open. Without coalescing, you pay NHTSA twice for the same pattern and race two identical payloads into the UI.

This post is about in-flight request coalescing: when a second caller asks for the same normalized VIN while a decode is already pending, return the same promise instead of opening a second upstream call. Debounce decides when to start after typing pauses. Stale-response guards decide which generation may commit. ETag caches skip repeats after a prior success. Here the focus is sharing one in-flight promise for identical VINs mid-request.

The failure mode

Typical sequence without coalesce:

User pastes VIN A; you fetch and keep the promise.
Before A resolves, the user pastes A again (or a React effect re-runs with the same value).
You start a second DecodeVinValues for the same normalized string.
NHTSA sees two identical requests; your quota and latency budget take a hit.
Both responses return; even with a generation guard you still wasted upstream work.

Debounce does not fix this: both pastes already cleared the debounce window as complete 17-character candidates. Stale-response ignore only drops late commits for different VINs; identical duplicates still double-fetch. An ETag cache helps after success, not while the first call is still pending.

One promise per normalized VIN in flight

Own a map from normalized VIN to the in-flight Promise. On decode start:

Normalize and validate the VIN.
If the map already has an entry for that key, return it.
Otherwise create the upstream promise, store it, and finally delete the key when settled (success or failure).

Callers that arrive mid-flight await the shared result. Distinct VINs still run in parallel -- coalesce is keyed by identity, not a global single-flight lock.

const VIN_RE = /^[A-HJ-NPR-Z0-9]{17}$/;

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[\s\-._]/g, "");
}

export type DecodeRow = Record<string, string>;

export type CoalesceMap = Map<string, Promise<DecodeRow>>;

export function coalesceDecode(
  inflight: CoalesceMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  if (!VIN_RE.test(vin)) {
    return Promise.reject(new Error("invalid_vin"));
  }

  const existing = inflight.get(vin);
  if (existing) return existing;

  const pending = fetchDecode(vin).finally(() => {
    // Only delete if we are still the mapped promise (avoid racing a newer entry).
    if (inflight.get(vin) === pending) inflight.delete(vin);
  });
  inflight.set(vin, pending);
  return pending;
}

The finally cleanup matters. Leaving stale entries after settle would force every later lookup to await a resolved promise forever -- or worse, skip a legitimate new fetch after a failed attempt. Deleting only when the map still points at this promise keeps a retry after failure honest.

Forbidden shortcuts

Product pressure often asks for:

A global single-flight lock so any second decode waits on the first -- even for a different VIN
Treating coalesce as a substitute for debounce (still fire on every keystroke, "share" junk candidates)
Skipping AbortSignal when the user clears the input -- shared waiters must still respect cancel UX
Caching failed 5xx forever inside the coalesce map so retries never leave
Coalescing by raw paste string without normalize (spaces or case create duplicate keys)

Refuse those. Coalesce identical valid in-flight work. Keep debounce for typing, generation stamps for commit races, and ETag/TTL caches for post-success repeats. Do not invent "instant decode" marketing that implies you skipped NHTSA when you only shared one call.

export function assertNoCoalesceAbuse(moduleSource: string): void {
  const banned = [
    /global.?single.?flight.?all.?vins/i,
    /skip.?nhtsa.?via.?coalesce/i,
    /instant.?decode.?no.?upstream/i,
    /coalesce.?partial.?digits/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(`Coalesce module misuse: ${re}`);
    }
  }
}

export async function decodeWithCoalesce(
  inflight: CoalesceMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
  onShared: () => void,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  const wasShared = inflight.has(vin);
  const row = await coalesceDecode(inflight, rawVin, fetchDecode);
  if (wasShared) onShared();
  return row;
}

Instrument onShared (or a metric) so you can see how often duplicate pastes were absorbed. That is observability, not a claim that decode is free or offline.

UI and API copy that stays honest

Prefer:

Silent share: second paste shows the same loading state without a second spinner flicker if you already own the session
Optional quiet log: "joined in-flight decode for this VIN"
Clear error if the shared promise rejects -- every waiter sees the same failure

Avoid:

"Cached instantly -- no NHTSA call" when you only coalesced an open request
Hiding a shared failure from secondary waiters
Showing success for VIN B because A's in-flight promise was incorrectly keyed

Quick checks

import assert from "node:assert/strict";

const inflight: CoalesceMap = new Map();
let calls = 0;
const fetchDecode = async (vin: string): Promise<DecodeRow> => {
  calls += 1;
  await new Promise((r) => setTimeout(r, 20));
  return { VIN: vin, Make: "TEST" };
};

const p1 = coalesceDecode(inflight, "1HGCM82633A004352", fetchDecode);
const p2 = coalesceDecode(inflight, "1hgcm82633a004352", fetchDecode);
assert.equal(p1, p2);
const [a, b] = await Promise.all([p1, p2]);
assert.equal(a.Make, "TEST");
assert.equal(b.Make, "TEST");
assert.equal(calls, 1);
assert.equal(inflight.size, 0);

const p3 = coalesceDecode(inflight, "1HGCM82633A004352", fetchDecode);
await p3;
assert.equal(calls, 2);

Review rule: coalesce modules must share by normalized VIN only while pending, clear on settle, and never claim to replace debounce, stale-response guards, or response caches.

Takeaway

In-flight coalescing collapses duplicate pastes of the same VIN into one upstream DecodeVinValues call. Pair it with debounce (start timing), generation stamps (commit races), and ETag caches (post-success repeats) -- do not substitute one for another. Your free VIN API stays kind to NHTSA when identical mid-flight work shares a promise, then clears so the next lookup can run honestly.

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

Adding Jittered Backoff to VIN Decode Retries Without Thundering Herds on NHTSA

Vin Lookup — Tue, 13 Oct 2026 08:47:05 +0000

A free VIN decode that retries NHTSA DecodeVinValues after a blip can become a herd: tabs, workers, and cron jobs fail together, sleep the same delay, and stampede the public endpoint. Exponential backoff without jitter still aligns those clocks. This post covers decorrelated jitter for VIN decode retries -- spread wake-ups without inventing success or treating sparse 200s as failures.

Circuit breakers, idempotency keys, and Retry-After parsing are separate posts. Here the job is: when a retry is justified, wait a randomized interval so peers do not collide.

When jitter matters (and when it does not)

Jitter helps after transient upstream pain:

Network timeouts and resets
HTTP 429 / 502 / 503 / 504 you already classified as retryable
Worker pools that re-queue the same VIN after a soft failure

Jitter does not fix:

Local VIN validation failures (length, I/O/Q, check digit)
HTTP 200 with empty feature fields (show "not provided," do not retry)
Product impatience ("Make was blank, hit NHTSA again")

If the attempt should never have retried, spreading the wake-up time only wastes quota more politely.

Prefer decorrelated jitter over fixed or equal jitter

Fixed sleeps and equal jitter (base * 2^attempt Â± 50%) still cluster when clients share the same attempt counter. Decorrelated jitter draws the next delay from a band based on the previous delay, so staggered clients drift apart instead of re-aligning.

export type JitterOpts = {
  baseMs: number;
  capMs: number;
  random?: () => number; // [0, 1)
};

export function decorrelatedJitterMs(
  previousDelayMs: number,
  opts: JitterOpts,
): number {
  const rnd = opts.random ?? Math.random;
  const prev = Math.max(opts.baseMs, previousDelayMs);
  const next = Math.min(
    opts.capMs,
    opts.baseMs + rnd() * (prev * 3 - opts.baseMs),
  );
  return Math.floor(next);
}

export async function sleep(ms: number): Promise<void> {
  await new Promise((r) => setTimeout(r, ms));
}

Start previousDelayMs at baseMs. After each failed attempt, compute the next sleep from the last one. Caps keep a hung tab from waiting forever; the random term keeps sibling tabs from sharing the same wake second.

Wire jitter into a decode retry loop

Keep classification outside the sleeper. The sleeper only spreads justified retries.

export type DecodeResult =
  | { ok: true; body: unknown }
  | { ok: false; retryable: boolean; status?: number };

export async function decodeWithJitteredRetries(
  attempt: () => Promise<DecodeResult>,
  opts: JitterOpts & { maxAttempts: number },
): Promise<DecodeResult> {
  let delay = opts.baseMs;
  let last: DecodeResult = { ok: false, retryable: false };

  for (let i = 0; i < opts.maxAttempts; i++) {
    last = await attempt();
    if (last.ok) return last;
    if (!last.retryable || i === opts.maxAttempts - 1) return last;
    await sleep(delay);
    delay = decorrelatedJitterMs(delay, opts);
  }
  return last;
}

Product rule: never mark a successful sparse decode as retryable. Empty feature fields or blank Make are finished decodes; retrying only burns quota.

Multi-tab and worker herds

Browsers open many tabs; workers fan out batches. First attempts can still correlate; jitter mainly helps on retries. Two habits shrink the first-hit herd:

Single-flight per VIN in-process before any sleep.
Small startup stagger for batch jobs (baseMs * random() before attempt 0) so cron fleets do not all fire on :00.

const inflight = new Map<string, Promise<DecodeResult>>();

export function singleFlightDecode(
  vin: string,
  run: () => Promise<DecodeResult>,
): Promise<DecodeResult> {
  const existing = inflight.get(vin);
  if (existing) return existing;
  const p = run().finally(() => inflight.delete(vin));
  inflight.set(vin, p);
  return p;
}

export async function batchDecodeStaggered(
  vins: string[],
  decodeOne: (vin: string) => Promise<DecodeResult>,
  opts: JitterOpts,
): Promise<DecodeResult[]> {
  const out: DecodeResult[] = [];
  for (const vin of vins) {
    const stagger = Math.floor((opts.random ?? Math.random)() * opts.baseMs);
    await sleep(stagger);
    out.push(
      await singleFlightDecode(vin, () =>
        decodeWithJitteredRetries(() => decodeOne(vin), {
          ...opts,
          maxAttempts: 3,
        }),
      ),
    );
  }
  return out;
}

Do not treat stagger as a substitute for rate limits. It only desynchronizes start times.

Forbidden product shortcuts

Retrying every empty catalog field "just in case"
Using the same fixed delay for all workers "for simpler logs"
Claiming jitter "guarantees" NHTSA availability
Hiding retry countdown as if the VIN were still decoding successfully
Disabling jitter in production because staging had one client

Show users a clear retrying state. Never upgrade a failed decode into a fabricated Make/Model while waiting.

Quick checks

import assert from "node:assert/strict";

const seq = [0.1, 0.9, 0.4];
let i = 0;
const random = () => seq[i++ % seq.length]!;

const d1 = decorrelatedJitterMs(100, {
  baseMs: 100,
  capMs: 5_000,
  random,
});
const d2 = decorrelatedJitterMs(d1, {
  baseMs: 100,
  capMs: 5_000,
  random,
});
assert.ok(d1 >= 100 && d1 <= 5_000);
assert.ok(d2 >= 100 && d2 <= 5_000);
assert.notEqual(d1, d2);

let calls = 0;
const result = await decodeWithJitteredRetries(
  async () => {
    calls += 1;
    if (calls < 3) return { ok: false, retryable: true, status: 503 };
    return { ok: true, body: { Make: "HONDA" } };
  },
  { baseMs: 1, capMs: 5, maxAttempts: 4, random: () => 0.5 },
);
assert.equal(result.ok, true);
assert.equal(calls, 3);

const sparse = await decodeWithJitteredRetries(
  async () => ({ ok: true, body: { TractionControl: "" } }),
  { baseMs: 1, capMs: 5, maxAttempts: 3 },
);
assert.equal(sparse.ok, true);

Review rule: jitter modules must not reclassify sparse successes as retryable, and must not remove randomness "for determinism" in production paths.

Takeaway

Decorrelated jitter turns justified VIN decode retries into staggered wake-ups instead of synchronized herds against NHTSA. Pair it with honest retry classification and in-process single-flight; leave circuit breakers and idempotency for their own layers. Your free decode stays kinder to the public API when failed attempts drift apart -- and sparse successes never retry.

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

Probing a Half-Open Circuit Breaker Before Restoring Full VIN Decode Traffic

Vin Lookup — Mon, 12 Oct 2026 09:21:59 +0000

Latency-aware circuit breakers (covered elsewhere) trip when NHTSA DecodeVinValues stays slow or hard-fails, then fail fast while open. The quiet next risk is how you leave open: flooding upstream when cooldown ends, or flipping straight to closed on the first lucky 200. This post is about the half-open probe phase -- admit a tiny number of trial decodes, score them strictly, and only then restore full VIN decode traffic. Initial open/trip behavior is covered elsewhere; here the focus is probing before you trust the circuit again.

Why half-open is not "open but friendlier"

State	Admission	Goal
Closed	Full interactive + batch (subject to other gates)	Normal decode
Open	Reject new upstream calls; optional cached last-good	Protect NHTSA and your pool
Half-open	Cap concurrent probes (often 1)	Learn if upstream recovered

Without a probe cap, cooldown expiry turns waiting forms into a thundering herd. Without strict scoring, one lucky 200 or one soft timeout can close the breaker while the next submits hang again.

Probe rules that stay honest

Define half-open explicitly:

After cooldownMs, transition open â†’ half_open and reset the probe counter.
Allow at most halfOpenMaxProbes in-flight (start with 1).
Extra submits while probing see circuit_half_open (or reuse circuit_open with a distinct UX string) -- not a second upstream call.
A probe that finishes inside budget and returns a typed success â†’ recordProbeSuccess â†’ closed.
A probe that times out, 5xxs, or network-fails â†’ recordProbeFailure â†’ open again with a fresh cooldown.

Do not count local validation rejects as probe failures. Do not treat a sparse-but-honest 200 (empty ABS, missing optional fields) as failure -- that is still upstream success for breaker purposes. Do not auto-close because "enough time passed" without a successful probe.

TypeScript sketch: half-open probe gate

type BreakerState = "closed" | "open" | "half_open";

export type HalfOpenConfig = {
  cooldownMs: number; // e.g. 20_000
  halfOpenMaxProbes: number; // e.g. 1
  slowThresholdMs: number; // e.g. 7000
};

export class HalfOpenProbeBreaker {
  private state: BreakerState = "closed";
  private openedAt = 0;
  private halfOpenInFlight = 0;

  constructor(private readonly cfg: HalfOpenConfig) {}

  /** Call before starting any DecodeVinValues work. */
  tryAdmit(): "allow" | "reject_open" | "reject_probe_cap" {
    if (this.state === "closed") return "allow";
    if (this.state === "open") {
      if (Date.now() - this.openedAt < this.cfg.cooldownMs) {
        return "reject_open";
      }
      this.state = "half_open";
      this.halfOpenInFlight = 0;
    }
    if (this.halfOpenInFlight >= this.cfg.halfOpenMaxProbes) {
      return "reject_probe_cap";
    }
    this.halfOpenInFlight += 1;
    return "allow";
  }

  recordProbeSuccess(): void {
    this.state = "closed";
    this.halfOpenInFlight = 0;
  }

  recordProbeFailure(): void {
    this.state = "open";
    this.openedAt = Date.now();
    this.halfOpenInFlight = 0;
  }

  /** Closed-path success/failure helpers omitted -- see open-trip article. */
  tripOpen(): void {
    this.state = "open";
    this.openedAt = Date.now();
    this.halfOpenInFlight = 0;
  }
}

export type ProbeResult<T> =
  | { ok: true; data: T }
  | {
      ok: false;
      reason: "circuit_open" | "probe_cap" | "upstream_slow" | "upstream";
    };

export async function decodeWithHalfOpenProbe<T>(
  breaker: HalfOpenProbeBreaker,
  call: (signal: AbortSignal) => Promise<T>,
  cfg: { slowThresholdMs: number },
): Promise<ProbeResult<T>> {
  const admit = breaker.tryAdmit();
  if (admit === "reject_open") {
    return { ok: false, reason: "circuit_open" };
  }
  if (admit === "reject_probe_cap") {
    return { ok: false, reason: "probe_cap" };
  }

  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(),
    cfg.slowThresholdMs,
  );
  const started = Date.now();
  try {
    const data = await call(controller.signal);
    clearTimeout(timer);
    breaker.recordProbeSuccess();
    return { ok: true, data };
  } catch {
    clearTimeout(timer);
    breaker.recordProbeFailure();
    const timedOut =
      controller.signal.aborted &&
      Date.now() - started >= cfg.slowThresholdMs - 50;
    return {
      ok: false,
      reason: timedOut ? "upstream_slow" : "upstream",
    };
  }
}

Gate every submit on tryAdmit() before spinners. When probe_cap rejects, keep the form interactive and say recovery is being tested -- do not queue silent retries that would become a second probe.

What a probe must not do

A half-open probe is still a real DecodeVinValues call with the same per-call budget. Do not lengthen timeouts "just this once" to force a success -- that hides slowness and closes the breaker on a lie. Do not skip VIN normalization, and do not fan out hedges: one probe means one upstream attempt until you reopen or re-trip. Prefer admitting an interactive candidate before batch when both wait for the probe slot.

UX for the probe window

Prefer:

"Decode recovering -- testing upstream; try again shortly" for probe_cap
One visible probe spinner, not N stacked loads
Optional labeled last-good cache while half-open rejects extras

Avoid:

Mapping probe_cap to "invalid VIN"
Opening all waiting forms the instant cooldown ends
Closing the breaker on wall-clock alone without a successful probe
Letting batch consume the only probe slot ahead of interactive users

Quick checks

import assert from "node:assert/strict";

const b = new HalfOpenProbeBreaker({
  cooldownMs: 1_000,
  halfOpenMaxProbes: 1,
  slowThresholdMs: 7_000,
});

b.tripOpen();
assert.equal(b.tryAdmit(), "reject_open");

// Simulate cooldown elapsed by tripping then forcing time via reopen path:
(b as unknown as { openedAt: number }).openedAt = Date.now() - 2_000;
assert.equal(b.tryAdmit(), "allow");
assert.equal(b.tryAdmit(), "reject_probe_cap");

b.recordProbeSuccess();
assert.equal(b.tryAdmit(), "allow");

b.tripOpen();
(b as unknown as { openedAt: number }).openedAt = Date.now() - 2_000;
assert.equal(b.tryAdmit(), "allow");
b.recordProbeFailure();
assert.equal(b.tryAdmit(), "reject_open");

Review rule: half-open modules must cap probes, distinguish reject reasons, and refuse to restore full traffic without a scored success.

Takeaway

Half-open is a probe phase, not a soft open. Admit a tiny trial budget after cooldown, score timeouts and hard failures strictly, reject excess submits with a clear recovery message, and only then restore full traffic. Keep this separate from the initial trip/open design. Your free decode proxy stays kind to NHTSA when recovery is earned by probes -- not by hope and a herd.

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

Token-Bucketing VIN Decode Clients So Bursts Do Not Exhaust NHTSA Quotas

Vin Lookup — Mon, 12 Oct 2026 09:05:43 +0000

A free VIN decode edge that lets every paste, refresh, and parallel tab fire DecodeVinValues immediately will burn through shared NHTSA courtesy quotas in a short burst -- even when each request is valid. Debounce collapses mid-typing keystrokes before a call starts. Load-shed drops optional enrichment when latency spikes. Retry jitter scatters wake-ups after a transient failure. This post is narrower: token-bucket the admitted decode rate so sustained and burst traffic stay inside a budget you chose.

The goal is honest rate control: admit up to a steady refill rate, allow a capped burst when tokens remain, and refuse excess without inventing cached catalog rows to fake a successful decode.

Why a token bucket (not only debounce)

Debounce answers "wait until typing pauses." It does not limit how many complete 17-character VINs a power user or multi-tab session can submit per second after each pause. Load-shed skips enrichment when p95 is high but still allows primary decodes to stampede. A token bucket asks: how many DecodeVinValues calls may leave this process in a window?

Typical pressure: paste-heavy tabs, warm serverless instances that each assume the full public quota, and cron warmers sharing one upstream identity. Without a local budget those paths compete until NHTSA returns 429.

Model: capacity, refill, tryTake

A classic bucket holds up to capacity tokens and refills at refillPerSecond. Each admitted decode costs one token. If the bucket is empty, refuse or wait -- do not silently invent a card.

export type TokenBucket = {
  capacity: number;
  tokens: number;
  refillPerSecond: number;
  updatedAtMs: number;
};

export function createTokenBucket(opts: {
  capacity: number;
  refillPerSecond: number;
  nowMs?: number;
}): TokenBucket {
  const now = opts.nowMs ?? Date.now();
  return {
    capacity: opts.capacity,
    tokens: opts.capacity,
    refillPerSecond: opts.refillPerSecond,
    updatedAtMs: now,
  };
}

export function refill(bucket: TokenBucket, nowMs: number): void {
  const elapsedSec = Math.max(0, (nowMs - bucket.updatedAtMs) / 1000);
  bucket.tokens = Math.min(
    bucket.capacity,
    bucket.tokens + elapsedSec * bucket.refillPerSecond,
  );
  bucket.updatedAtMs = nowMs;
}

export type TakeResult =
  | { ok: true; remaining: number }
  | { ok: false; retryAfterMs: number; remaining: number };

export function tryTake(
  bucket: TokenBucket,
  nowMs: number,
  cost = 1,
): TakeResult {
  refill(bucket, nowMs);
  if (bucket.tokens >= cost) {
    bucket.tokens -= cost;
    return { ok: true, remaining: bucket.tokens };
  }
  const need = cost - bucket.tokens;
  const retryAfterMs = Math.ceil(
    (need / bucket.refillPerSecond) * 1000,
  );
  return { ok: false, retryAfterMs, remaining: bucket.tokens };
}

capacity is the burst you tolerate. refillPerSecond is the sustained rate you will send toward NHTSA from this client identity. Tune both from observed courtesy limits and your multi-tenant share -- not from assuming unlimited public quota.

Wire the bucket before fetch

export type DecodeAdmit =
  | { admitted: true; remaining: number }
  | {
      admitted: false;
      retryAfterMs: number;
      reason: "token_bucket_empty";
    };

export function admitDecode(
  bucket: TokenBucket,
  nowMs: number,
): DecodeAdmit {
  const take = tryTake(bucket, nowMs, 1);
  if (take.ok) {
    return { admitted: true, remaining: take.remaining };
  }
  return {
    admitted: false,
    retryAfterMs: take.retryAfterMs,
    reason: "token_bucket_empty",
  };
}

export async function decodeWithTokenBucket(opts: {
  vin: string;
  bucket: TokenBucket;
  nowMs: number;
  fetchDecode: (vin: string) => Promise<Record<string, string>>;
}): Promise<
  | { status: "ok"; fields: Record<string, string>; remaining: number }
  | {
      status: "rate_limited";
      retryAfterMs: number;
      fields: null;
    }
> {
  const admit = admitDecode(opts.bucket, opts.nowMs);
  if (!admit.admitted) {
    return {
      status: "rate_limited",
      retryAfterMs: admit.retryAfterMs,
      fields: null,
    };
  }
  const fields = await opts.fetchDecode(opts.vin);
  return { status: "ok", fields, remaining: admit.remaining };
}

When rate_limited, return a clear retry hint. Do not refill the UI from a sibling VIN cache and pretend the limited call succeeded.

Forbidden upgrades

Product pressure often asks for:

Serving Make/Model folklore when the bucket is empty so the form "still works"
Sharing one oversized bucket across all tenants so one scraper starves everyone
Setting capacity to Infinity "until we see 429" (you will)
Collapsing debounce, load-shed, and token-bucket into one vague "slow down" flag

Refuse those. Debounce delays start-of-typing. Load-shed drops enrichment. Token-bucket limits admitted primary calls. Keep the tools separate.

export function rateLimitLines(result: {
  status: string;
  retryAfterMs?: number;
}): string[] {
  if (result.status === "rate_limited") {
    return [
      "Decode rate limited -- local token bucket empty",
      `Retry after roughly ${result.retryAfterMs ?? 0} ms`,
    ];
  }
  return ["Decode admitted under token-bucket budget"];
}

export function assertNoTokenBucketInvent(moduleSource: string): void {
  const banned = [
    /typical for this model/i,
    /served from sibling vin/i,
    /quota.?unlimited/i,
    /fake.?success.?while.?limited/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `Token-bucket module must not invent decode results: ${re}`,
      );
    }
  }
}

UI copy that stays honest

Prefer:

"Too many decodes right now -- try again in a moment"
"Rate limited locally to protect NHTSA quota"

Avoid:

Grey cards filled with "usual for this model year" while limited
Silent success toasts when tryTake failed

Quick checks

import assert from "node:assert/strict";

const b = createTokenBucket({
  capacity: 2,
  refillPerSecond: 1,
  nowMs: 0,
});
assert.equal(tryTake(b, 0).ok, true);
assert.equal(tryTake(b, 0).ok, true);
const denied = tryTake(b, 0);
assert.equal(denied.ok, false);
if (!denied.ok) {
  assert.ok(denied.retryAfterMs > 0);
}

refill(b, 1000);
assert.equal(tryTake(b, 1000).ok, true);

const limited = await decodeWithTokenBucket({
  vin: "1HGCM82633A004352",
  bucket: createTokenBucket({ capacity: 0, refillPerSecond: 1, nowMs: 0 }),
  nowMs: 0,
  fetchDecode: async () => ({ Make: "HONDA" }),
});
assert.equal(limited.status, "rate_limited");
assert.equal(limited.fields, null);
assert.ok(
  rateLimitLines(limited).some((l) => /token bucket empty/i.test(l)),
);
assert.ok(
  !rateLimitLines(limited).some((l) =>
    /typical for this model|sibling vin/i.test(l),
  ),
);

Review rule: token-bucket modules must not invent catalog fields on refusal, and must stay distinct from debounce and load-shed.

Takeaway

Token-bucket VIN decode clients so bursts cannot exhaust the NHTSA-facing budget you share. Cap capacity, refill steadily, refuse cleanly when empty, and keep debounce, load-shed, and retry jitter as separate tools. Your free VIN API stays kind to upstream when admitted calls match a real budget -- without inventing decode results over a dry bucket.

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

Caching VIN Decodes with ETags So Repeat Lookups Skip Redundant NHTSA Calls

Vin Lookup — Mon, 12 Oct 2026 08:48:48 +0000

A free VIN decode proxy that always re-fetches DecodeVinValues for the same normalized VIN wastes NHTSA quota on identical payloads. Idempotency keys (covered elsewhere) collapse retries of one button press. Stale-response guards (also covered elsewhere) drop late arrivals after a newer VIN wins. This post is a different lever: an HTTP cache with ETags so a repeat lookup for the same VIN can answer 304 Not Modified (or serve a fresh cached body) without another upstream call.

The goal is narrow: store a decode body keyed by normalized VIN, emit an ETag, honor If-None-Match, and skip NHTSA when the representation is unchanged. Do not confuse this with client idempotency keys, debounce on partial digits, or "cache forever without revalidation."

Where unconditional fetches hurt

Every successful DecodeVinValues costs a free-quota unit. Unconditional re-decode fails when traffic repeats:

A user toggles tabs and re-submits the same VIN minutes later
A BFF refreshes a card that already holds yesterday's catalog snapshot
Monitoring probes the same golden VIN on a schedule
Two tabs race the same normalized VIN after a page reload

Each case is a representation-cache problem. Idempotency protects one attempt's retries; ETag caching protects repeat intents for the same VIN while still allowing deliberate revalidation.

Shape the cache entry

Key on the normalized VIN (and optional decode profile). Store the JSON body, a strong ETag, and a stored-at timestamp for TTL decisions.

export type DecodeCacheEntry = {
  vinNormalized: string;
  body: string;
  etag: string;
  storedAt: number;
  maxAgeMs: number;
};

export type DecodeCache = Map<string, DecodeCacheEntry>;

export function makeEtag(body: string): string {
  // Strong validator from body bytes; swap for sha256 in production.
  let h = 0;
  for (let i = 0; i < body.length; i++) {
    h = (Math.imul(31, h) + body.charCodeAt(i)) | 0;
  }
  return `"vin-${(h >>> 0).toString(16)}"`;
}

export function putDecode(
  cache: DecodeCache,
  vinNormalized: string,
  body: string,
  now = Date.now(),
  maxAgeMs = 86_400_000,
): DecodeCacheEntry {
  const entry: DecodeCacheEntry = {
    vinNormalized,
    body,
    etag: makeEtag(body),
    storedAt: now,
    maxAgeMs,
  };
  cache.set(vinNormalized, entry);
  return entry;
}

export function isFresh(entry: DecodeCacheEntry, now = Date.now()): boolean {
  return now - entry.storedAt < entry.maxAgeMs;
}

The ETag is a validator for the cached representation, not a client attempt id. A new upstream body that differs produces a new ETag; an unchanged body keeps the same validator.

Honor If-None-Match before upstream

On a decode request, check the cache first. If the entry is fresh and the client's If-None-Match matches, return 304 with no body and no NHTSA call. If fresh without a matching precondition, return 200 with the cached body. Only miss or stale entries reach DecodeVinValues.

export type CacheResult =
  | { status: 304; etag: string }
  | { status: 200; body: string; etag: string; fromCache: boolean };

export async function decodeWithEtag(opts: {
  cache: DecodeCache;
  vinNormalized: string;
  ifNoneMatch?: string | null;
  fetchUpstream: (vin: string) => Promise<string>;
  now?: number;
}): Promise<CacheResult> {
  const now = opts.now ?? Date.now();
  const hit = opts.cache.get(opts.vinNormalized);

  if (hit && isFresh(hit, now)) {
    if (opts.ifNoneMatch && opts.ifNoneMatch === hit.etag) {
      return { status: 304, etag: hit.etag };
    }
    return {
      status: 200,
      body: hit.body,
      etag: hit.etag,
      fromCache: true,
    };
  }

  const body = await opts.fetchUpstream(opts.vinNormalized);
  const entry = putDecode(opts.cache, opts.vinNormalized, body, now);
  return {
    status: 200,
    body: entry.body,
    etag: entry.etag,
    fromCache: false,
  };
}

Wire ETag and Cache-Control on the HTTP response. Clients that store the ETag can send If-None-Match on the next lookup and skip payload transfer when nothing changed. Prefer a modest max-age (hours to a day for a free decode card), not forever.

Normalize the VIN before the cache key (uppercase, strip separators) so casing variants share one entry. Include profile or format in the key if your proxy returns different field subsets for the same VIN.

What this is not

Product pressure often asks for:

Treating ETag like an idempotency key for double-clicks (wrong layer)
Caching forever with no TTL so stale catalog rows never refresh
Keying only on raw user input so 1HGCM... and 1hgcm... miss each other
Returning 304 when the body actually changed upstream after TTL expiry
Skipping NHTSA on every hit even when the operator requested a forced refresh

Refuse those. Support an explicit Cache-Control: no-cache or ?refresh=1 path that bypasses freshness and revalidates. Keep ETag caching distinct from debounce, hedges, and attempt keys.

export function shouldBypassCache(headers: {
  cacheControl?: string | null;
  refresh?: string | null;
}): boolean {
  const cc = (headers.cacheControl ?? "").toLowerCase();
  if (cc.includes("no-cache") || cc.includes("no-store")) return true;
  return headers.refresh === "1" || headers.refresh === "true";
}

Quick checks

import assert from "node:assert/strict";

const cache: DecodeCache = new Map();
let upstreamCalls = 0;
const fetchUpstream = async (vin: string) => {
  upstreamCalls += 1;
  return JSON.stringify({ VIN: vin, Make: "HONDA" });
};

const first = await decodeWithEtag({
  cache,
  vinNormalized: "1HGCM82633A004352",
  fetchUpstream,
});
assert.equal(first.status, 200);
assert.equal(first.fromCache, false);
assert.equal(upstreamCalls, 1);

const second = await decodeWithEtag({
  cache,
  vinNormalized: "1HGCM82633A004352",
  ifNoneMatch: first.etag,
  fetchUpstream,
});
assert.equal(second.status, 304);
assert.equal(upstreamCalls, 1);

const third = await decodeWithEtag({
  cache,
  vinNormalized: "1HGCM82633A004352",
  fetchUpstream,
});
assert.equal(third.status, 200);
assert.equal(third.fromCache, true);
assert.equal(upstreamCalls, 1);

Review rule: ETag modules must skip upstream on fresh matching validators, revalidate after TTL, and never pretend an attempt key is a representation validator.

Takeaway

ETag caching lets repeat VIN lookups reuse a fresh DecodeVinValues representation and answer 304 when the client already holds that validator. Pair a VIN-keyed store, a strong ETag, and a modest TTL. Keep this separate from idempotency keys and input debounce. Offer a forced-refresh path for operators who need a live upstream read. Your free proxy stays kind to NHTSA quota when identical catalog snapshots stop costing a second upstream call.

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

Negatively Caching Invalid VIN Responses So Bad Digits Do Not Hammer NHTSA

Vin Lookup — Fri, 09 Oct 2026 09:22:07 +0000

A free VIN decode that always forwards every paste to live NHTSA DecodeVinValues pays upstream cost when users typo a check digit, paste seventeen zeros, or retry the same invalid string. Positive ETag caches and make-pattern warmup (covered elsewhere) store successful bodies. This post is different: a negative cache for VINs you already know are invalid or that vPIC already refused, so bad digits do not hammer NHTSA on every retry.

The goal is honest short-circuit: remember "this normalized VIN is not worth another upstream call for a while," show a clear invalid/error state, and never invent a successful decode card from a negative entry.

Negative cache vs positive caches

Use a negative cache when:

Client-side checks (length, charset, check digit) already fail before HTTP
Upstream returned a clear "no decode / error / empty Results" for that VIN
The same bad paste repeats within a short TTL (fat-finger retries, bot loops)

Do not use negative cache to store successful DecodeVinValues bodies (ETag / warmup territory), invent folklore Make/Model/Year, suppress live calls forever (bound TTL), or treat 429/outages as permanent "invalid VIN."

When the entry expires or the failure was transient (5xx, timeout), allow a live retry. Client-invalid shapes can use a longer TTL than soft upstream empties.

Classify before you store

Separate client-invalid (never call upstream) from upstream-negative (you called, got a clear no-decode). Both can live in one map keyed by normalized VIN, with different reasons and TTLs.

export type NegReason =
  | "client-length"
  | "client-charset"
  | "client-check-digit"
  | "upstream-empty"
  | "upstream-error";

export type NegEntry = {
  vinNormalized: string;
  reason: NegReason;
  storedAt: number; // epoch ms
  ttlMs: number;
  message: string; // user-safe, no invented specs
};

export type NegStore = Map<string, NegEntry>;

const CLIENT_TTL_MS = 60 * 60 * 1000; // 1h for obvious typos
const UPSTREAM_TTL_MS = 15 * 60 * 1000; // 15m for empty/error bodies

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[^A-HJ-NPR-Z0-9]/g, "");
}

export function clientInvalidReason(vin: string): NegReason | null {
  if (vin.length !== 17) return "client-length";
  if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) return "client-charset";
  // Check-digit algorithm omitted for brevity; return "client-check-digit" on fail
  return null;
}

export function putNegative(
  store: NegStore,
  vinNormalized: string,
  reason: NegReason,
  message: string,
  nowMs = Date.now(),
): NegEntry {
  const ttlMs =
    reason.startsWith("client-") ? CLIENT_TTL_MS : UPSTREAM_TTL_MS;
  const entry: NegEntry = {
    vinNormalized,
    reason,
    storedAt: nowMs,
    ttlMs,
    message,
  };
  store.set(vinNormalized, entry);
  return entry;
}

export function getNegative(
  store: NegStore,
  vinNormalized: string,
  nowMs = Date.now(),
): NegEntry | null {
  const hit = store.get(vinNormalized);
  if (!hit) return null;
  if (nowMs - hit.storedAt >= hit.ttlMs) {
    store.delete(vinNormalized);
    return null;
  }
  return hit;
}

Never put a successful body into this map. Never upgrade a negative hit into Make/Model/Year rows.

Decode path with short-circuit

export type DecodeOutcome =
  | { kind: "negative"; entry: NegEntry }
  | { kind: "live"; body: Record<string, string | null> }
  | { kind: "transient-error"; status: number };

export async function decodeWithNegCache(
  store: NegStore,
  rawVin: string,
  fetchLive: (vin: string) => Promise<{
    ok: boolean;
    status: number;
    body: Record<string, string | null> | null;
    empty: boolean;
  }>,
  nowMs = Date.now(),
): Promise<DecodeOutcome> {
  const vin = normalizeVin(rawVin);
  const cached = getNegative(store, vin, nowMs);
  if (cached) return { kind: "negative", entry: cached };

  const clientReason = clientInvalidReason(vin);
  if (clientReason) {
    const entry = putNegative(
      store,
      vin,
      clientReason,
      "VIN failed local validation -- not sent to NHTSA",
      nowMs,
    );
    return { kind: "negative", entry };
  }

  const live = await fetchLive(vin);
  if (!live.ok && live.status >= 500) {
    return { kind: "transient-error", status: live.status };
  }
  if (!live.ok || live.empty || !live.body) {
    const entry = putNegative(
      store,
      vin,
      live.ok ? "upstream-empty" : "upstream-error",
      "No decode available from vPIC for this VIN",
      nowMs,
    );
    return { kind: "negative", entry };
  }
  return { kind: "live", body: live.body };
}

Transient 5xx stays out of the negative store (or uses a very short TTL if you must). That keeps outages from branding a good VIN as permanently invalid.

Forbidden upgrades

Product pressure often asks for:

Serving a fake "success" card from a negative hit so the UI looks complete
Infinite TTL so one empty response never rechecks after catalog updates
Collapsing rate-limit 429 into "invalid VIN" negatives
Mixing negative keys with positive ETag bodies in one undifferentiated blob

Refuse those. Negative cache is a courtesy throttle and UX shortcut -- not a second invent-specs path.

export function assertNoNegInvent(moduleSource: string): void {
  const banned = [
    /invent.*(make|model|year)/i,
    /negative.*success.?card/i,
    /forever.?invalid/i,
    /treat.?429.?as.?invalid/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(`Negative cache must not invent decode cards: ${re}`);
    }
  }
}

export function uiMessage(entry: NegEntry): string {
  return entry.message;
}

UI copy that stays honest

Prefer:

"VIN failed local validation -- not sent to NHTSA"
"No decode available from vPIC for this VIN (cached briefly)"
"Temporary upstream error -- try again shortly" for transient failures

Avoid Make/Model/Year from memory on negative hits, "invalid forever" without TTL disclosure, and silent success styling on a negative entry.

Quick checks

import assert from "node:assert/strict";

const store: NegStore = new Map();
const short = normalizeVin("123");
assert.equal(clientInvalidReason(short), "client-length");

const neg = putNegative(
  store,
  short,
  "client-length",
  "VIN failed local validation -- not sent to NHTSA",
  1_000,
);
assert.equal(getNegative(store, short, 1_000)?.reason, "client-length");
assert.equal(getNegative(store, short, 1_000 + CLIENT_TTL_MS)?.reason, undefined);

assert.equal(uiMessage(neg).includes("Make"), false);
assert.ok(!/standard|verified|package/i.test(uiMessage(neg)));

Review rule: negative-cache modules must not invent successful decode fields. Bound TTL; separate transient errors from invalid VINs.

Takeaway

A negative cache stops bad digits and known empty upstream results from hammering NHTSA on every retry. Store reason + TTL, short-circuit with honest UI copy, and leave successful bodies to ETag and warmup paths. Invalid pastes stay remembered briefly -- never upgraded into invented catalog rows.

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

Ignoring Stale VIN Decode Responses After a Newer Request Wins the Race

Vin Lookup — Fri, 09 Oct 2026 09:05:31 +0000

A free VIN decode form often fires DecodeVinValues (or your thin proxy) on every paste or debounce tick. Users type fast: VIN A starts, then VIN B starts before A returns. If you apply every resolved promise, the card can briefly show B's Make/Model and then flip back to A's older payload -- or paint A's error under B's input.

This post is about a request-id / generation-counter stale-response guard: bump a monotonic id when you start a decode, stamp it on the in-flight promise, and commit UI state only when that id still matches the latest generation. AbortSignal, input-clear cancel UX, and timeout-overlap races are separate topics. Here the focus is out-of-order success and error payloads after a newer request already owns the screen.

The failure mode

Typical buggy sequence:

User pastes VIN A; you fetch and keep the promise.
Before A resolves, the user pastes VIN B; you start a second fetch (with or without aborting A).
B returns first; you paint Make/Model for B. Good so far.
A returns later; a careless .then still calls setResult(rowA).
The input shows B, the card shows A's identity. Support tickets look like "decode lies."

Aborting A helps when cancel is honored. It fails when the proxy already finished, a shared promise lacks a generation stamp, or you only abort on empty input. A generation counter (or UUID request id) is the last line of defense: late bodies must be ignored when no longer current.

One generation per decode start

Bump generation (or mint a requestId) every time you start a decode for a normalized VIN. Store the stamp on the session. Every success and failure path checks session.generation === latestGeneration before mutating result, error, or loading.

export type DecodeRow = Record<string, string>;

export type DecodeUiState = {
  vin: string | null;
  row: DecodeRow | null;
  error: string | null;
  loading: boolean;
  generation: number;
};

export type DecodeSession = {
  generation: number;
  vinNormalized: string;
};

export function nextGeneration(state: DecodeUiState): number {
  return state.generation + 1;
}

export function isCurrent(
  session: DecodeSession,
  latestGeneration: number,
): boolean {
  return session.generation === latestGeneration;
}

export function applyDecodeSuccess(
  state: DecodeUiState,
  session: DecodeSession,
  row: DecodeRow,
): DecodeUiState {
  if (!isCurrent(session, state.generation)) {
    return state; // stale -- newer request already owns the UI
  }
  return {
    ...state,
    vin: session.vinNormalized,
    row,
    error: null,
    loading: false,
  };
}

export function applyDecodeError(
  state: DecodeUiState,
  session: DecodeSession,
  error: string,
): DecodeUiState {
  if (!isCurrent(session, state.generation)) {
    return state;
  }
  return {
    ...state,
    vin: session.vinNormalized,
    row: null,
    error,
    loading: false,
  };
}

The guard is deliberately boring. Stale successes and stale errors both refuse to write. A late "404 from NHTSA" for A must not wipe B's good row. Treat "current generation" as the single source of truth for which VIN owns the card -- not whichever promise happens to settle last.

Wire it at the promise boundary

Start the session when you kick off work. Pass the same session into both branches. Do not close over a mutable let result without the check.

export async function runDecode(
  state: DecodeUiState,
  vinNormalized: string,
  fetchRow: (vin: string) => Promise<DecodeRow>,
): Promise<DecodeUiState> {
  const generation = nextGeneration(state);
  const session: DecodeSession = { generation, vinNormalized };
  let next: DecodeUiState = {
    ...state,
    generation,
    loading: true,
    error: null,
  };

  try {
    const row = await fetchRow(vinNormalized);
    next = applyDecodeSuccess(next, session, row);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Decode failed";
    next = applyDecodeError(next, session, message);
  }
  return next;
}

If setState lands after another start bumped generation, applyDecodeSuccess no-ops. Product guarantee: newer request wins; older responses become no-ops.

What this is not

Do not conflate this guard with AbortSignal plumbing, input-clear cancel UX, timeout-only races, or SWR cache revalidation. Those are adjacent. You can combine abort + generation: abort reduces wasted work; generation prevents wrong paint when abort is incomplete.

Forbidden "fixes"

Product pressure often asks for:

"Just always take the last response that arrives" without comparing ids (that is the bug)
Showing a spinner until all in-flight promises settle (hangs the UI on abandoned A)
Merging row A and row B fields because "some data is better than none"
Skipping the guard for errors ("errors are harmless") -- they are not; they blank good cards
Reusing one global promise for every VIN without stamping which VIN it belongs to

Refuse those. One stamp per start; commit only if current. The expensive bug is not a wasted network call -- it is a trustworthy-looking card that silently shows the wrong vehicle.

Quick checks

import assert from "node:assert/strict";

const base: DecodeUiState = {
  vin: null,
  row: null,
  error: null,
  loading: false,
  generation: 0,
};

const sessionA: DecodeSession = { generation: 1, vinNormalized: "A".repeat(17) };
const sessionB: DecodeSession = { generation: 2, vinNormalized: "B".repeat(17) };

let state: DecodeUiState = { ...base, generation: 2, loading: true };
state = applyDecodeSuccess(state, sessionB, { Make: "Beta" });
assert.equal(state.row?.Make, "Beta");

// Late A must not overwrite B
state = applyDecodeSuccess(state, sessionA, { Make: "Alpha" });
assert.equal(state.row?.Make, "Beta");

// Late A error must not wipe B
state = applyDecodeError(state, sessionA, "upstream timeout");
assert.equal(state.row?.Make, "Beta");
assert.equal(state.error, null);

assert.equal(isCurrent(sessionA, 2), false);
assert.equal(isCurrent(sessionB, 2), true);

Review rule: decode commit paths must ignore mismatched generations. Never apply a resolved body solely because loading was once true.

Takeaway

Out-of-order VIN decode responses are normal on a chatty form. Stamp every start with a request id or generation counter, and ignore successes and errors that no longer match. Your free VIN UI stays trustworthy when the newest request owns the card -- and older payloads become silent no-ops instead of identity flip-flops.

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