Direct answer
OUT_OF_STOCK and UNKNOWN answer different questions. OUT_OF_STOCK means a source returned a fresh, interpretable no-stock observation. UNKNOWN means the system cannot currently make an authoritative stock claim because the response was blocked, incomplete, expired, or otherwise unverified. Treating both states as “no inventory” creates avoidable shortage alerts and can trigger the wrong purchasing response.
Who this is for and what it does not promise
This guide is for procurement, engineering, and operations teams that depend on automated alerts. It helps define safe state transitions for a watchlist. It does not promise that a fresh “in stock” response reserves inventory, and it does not replace the supplier’s checkout, allocation, credit, or fulfillment decision.
Read the signal as a state machine
| State | Meaning | Recommended action |
|---|---|---|
IN_STOCK | A fresh successful source response reports available stock | Show the source and timestamp; continue monitoring |
OUT_OF_STOCK | A fresh successful source response reports no available stock | Alert according to policy; confirm high-impact cases |
UNKNOWN | There is not enough evidence to make a stock claim | Retry or request review; do not convert to zero |
BLOCKED | Access was denied or a challenge prevented collection | Fix credentials/access or use an approved alternate source |
ERROR | The request or response failed unexpectedly | Record the failure, apply backoff, and retry safely |
STALE | The last successful evidence is older than the accepted window | Display age clearly; require a refresh before purchasing |
These are monitoring semantics, not promises made by every supplier. A provider may use different response fields or status names. The monitoring layer should preserve the original source response boundary and translate it into a small internal vocabulary without hiding why the translation happened.
Why collection failures happen
Common causes include expired credentials, rate limits, regional storefront differences, network timeouts, changed response formats, scheduled maintenance, and pages that require an interactive session. An official API surface such as DigiKey ProductSearch can still return an error or an incomplete match; an aggregator such as Mouser’s API Hub has its own access and data rules. The correct operational response is to classify the failure, not to invent a stock value.
Build alerts around evidence quality
Show the last successful observation
When a refresh fails, keep the last good observation visible with its age and source. This is more useful than replacing it with a misleading zero. The interface should make it obvious that the current reading is historical.
Separate operational alerts from buyer alerts
A blocked credential is an operations alert. A confirmed stockout is a buyer alert. They may concern the same MPN, but they need different owners, severity, and follow-up steps.
Confirm consequential changes
For a critical BOM line, require a second authoritative check or a manual supplier confirmation before changing a purchase plan. A second source does not automatically override the first; it makes the disagreement visible and gives a buyer a reason to investigate.
Expire stale evidence deliberately
The acceptable age depends on the component, lead time, and decision. Define it explicitly. A stable planning report may tolerate older evidence, while a last-minute production shortage needs a much tighter window.
Product workflow
Chip Monitor keeps stock, price, and lead-time changes tied to a source and last-checked time. Its supplier integrations are designed for watchlist decisions where “could not verify” must remain different from “confirmed unavailable.”
See the DigiKey monitoring workflow for a concrete channel example.
Evidence boundary
No monitoring state guarantees allocation, shipment, or checkout success. Supplier data can change between collection and purchase, and access policies can change without notice. Use UNKNOWN, BLOCKED, ERROR, and STALE to protect decisions from false certainty, then recheck the official supplier before acting on a critical part.