Supplier API Failures: Keys, Limits, and Timeouts

Direct answer

When a supplier API fails, classify the failure before changing a stock status. Check authentication, permissions, rate limits, timeouts, response shape, and source freshness in order. Preserve the last valid observation with its timestamp, mark the connector state, and never turn an error into out-of-stock.

Why the runbook matters

An inventory monitor sits between a supplier system and a purchasing decision. A request can fail because a key expired, a quota was reached, a network timed out, or a parser no longer understands the response. None of those events proves that the part is unavailable.

The operational goal is to make the system honest during blindness. MPNRadar can show the monitoring record, while API, aggregator, or web page sourcing helps compare transport choices.

First classify the incident

Use a top-level connector state:

Keep the incident state beside the part observation. A healthy connector can return an explicit out-of-stock result; a broken connector cannot.

Step 1: Check authentication and permissions

Confirm:

• the correct environment and account;
• the token or key has not expired;
• the required OAuth or app consent is active;
• the request uses the expected headers and endpoint;
• the account has access to the product or region; and
• secrets are loaded from the approved secret store.

Do not print a token into logs while debugging. Record a redacted key identifier, account, endpoint, and error class. DigiKey's developer documentation describes OAuth, shared API principles, rate limits, and status-code handling. Use the provider's current guidance for the exact flow.

Step 2: Check rate limits before retrying

Repeated retries can turn a small problem into a longer block. Record:

• response status and provider error code;
• request count and time window;
• retry-after value, if supplied;
• connector concurrency;
• backoff schedule; and
• next allowed attempt.

DigiKey's API resources describe rate limits and shared API principles. A source-specific quota must be configured in the connector; do not guess that every supplier uses the same limit.

Use exponential backoff with a maximum delay and jitter where appropriate. Queue lower-priority MPNs behind critical items only if the provider terms and internal fairness rules allow it. Do not bypass a provider limit with many uncontrolled keys.

Step 3: Check timeout and network health

A timeout has several possible causes:

• DNS or TLS problem;
• provider latency;
• oversized query or response;
• local connection pool exhaustion;
• proxy or firewall failure; or
• a client timeout shorter than the provider's normal response.

Capture duration, endpoint, region, query size, and retry count. Separate a provider timeout from a client cancellation. If only one region fails, compare with a controlled health check; do not label every supplier result stale without evidence.

Step 4: Check response shape and parsing

If HTTP succeeds but the parser fails, keep the raw response reference in the protected evidence store and mark PARSE_FAILED. Do not return a default quantity of zero.

Test for:

• missing fields;
• renamed or nested fields;
• empty result arrays;
• error objects returned with a success code;
• pagination or partial response markers; and
• changed units, currency, or region names.

Mouser's API documentation describes product-data and cart operations. A successful HTTP response does not prove that every product field required by a monitor is present; validate the fields before normalization.

Step 5: Protect freshness

When the connector is down:

``text lastValidObservation = retain with its original observedAt currentConnectorState = incident state displayedStockState = stale or unknown nextAction = repair and re-observe ``

The dashboard may show the last value for context, but it should display its age. Unknown stock is not out of stock describes this boundary.

A response policy for critical parts

For a critical MPN:

1. retry only within the source's allowed policy;
2. check a second approved source if one exists;
3. create an operational incident with owner and deadline;
4. keep the last valid observation dated; and
5. escalate to procurement if freshness exceeds the build policy.

A second source can add context, but it does not repair the failed source. Keep the source-specific incident visible.

Close the incident with evidence

The close record should include:

• root-cause category;
• first and last failure time;
• affected sources or MPNs;
• code, config, or key change;
• a successful test request;
• the first fresh observation after recovery; and
• any missed freshness window.

Do not backfill an observation time with the recovery time. Preserve the real time at which the supplier data was observed.

Monitoring the monitor

Track connector health separately from product signals:

One successful request is not enough if the critical MPNs were skipped or the response was partial.

Questions operations teams ask

Should I retry every error?

No. Retry transient network or provider responses under a bounded policy. Fix authentication, permission, and parser errors before retrying at volume.

Can I show the last known stock as current?

No. Show it with its timestamp and stale state. The current value is unknown until a valid fresh observation arrives.

Is a second supplier API a fallback for all failures?

It can provide another signal if the MPN, region, package, and quantity basis align. It cannot prove that the first source recovered or that two supplier semantics are equivalent.

Final review

A useful API runbook tells an operator what failed, what remains known, when the last valid observation occurred, how to repair the connector, and when procurement must act. Keep secrets out of logs and preserve the error as an operational event.

MPNRadar supports monitoring evidence but does not guarantee supplier API uptime or market truth. Use the current supplier documentation and account terms before changing a connector. Continue with normalize distributor inventory data, BOM monitoring, and MPNRadar pricing.

Set incident severity

Not every connector failure needs the same response. Use the watch-list impact:

Severity describes business impact, not the HTTP status alone. A 200 response with an unusable payload may be high impact; a short timeout on a non-critical item may be low impact.

Use a retry decision table

``text Authentication or permission error -> stop retries and repair access Rate limit -> respect provider window and back off Transient network error -> bounded retry, then mark timeout Parser error -> quarantine response and review mapping Empty valid result -> verify query and source semantics ``

The table should be part of the connector configuration. It keeps an operator from applying a network retry to a permission problem or treating an empty result as a stock fact.

Rotate credentials without losing coverage

When a key or token is rotated, record the change window, connector owner, test request, and first fresh observation. Load the new credential from the approved secret store and revoke the old one according to the provider and company policy. Never place the new or old secret in the incident ticket.

If rotation cannot happen immediately, mark the affected source stale and use the approved fallback. Do not create an untracked key at the command line just to make the dashboard green.

Add a manual fallback with a deadline

For a critical list, define whether a buyer can check an approved supplier page or request a quote while the API is down. The fallback should record the exact MPN, quantity, region, source, and observation time. It should also have a close date so a manual workaround does not become an invisible permanent path.

Review failures after recovery

Compare the failure window with the watch-list schedule. Identify which MPNs were skipped, which alerts were suppressed, and which decisions relied on old evidence. The recovery is not complete until the connector has produced valid fresh observations for the critical set.

Publish a recovery message

When the source is healthy again, tell the affected owners what changed and what remains uncertain. Include the recovered connector, first fresh observation time, any MPNs still missing, and whether procurement must revisit a decision. A recovery message closes the operational loop without claiming that the supplier's market data is perfect.

The message should link to the incident and the validation result, while keeping credentials and private supplier data in the protected system.

Audience and limitations

This article applies to procurement, engineering, and operations teams monitoring electronic components. It does not promise supplier accuracy, stock, price, delivery, lifecycle status, equivalence, or any specific business outcome; current source evidence and internal approvals remain the authority.