直接回答
供应商 API 失败时，先分类故障，再改变库存状态。依次检查认证、权限、限流、超时、响应结构和来源新鲜度，保留带有原始时间戳的最后一次有效观测，标记连接器状态，绝不能把错误转换成缺货。
为什么需要故障手册
库存监控位于供应商系统和采购决策之间。请求可能因密钥过期、权限不足、配额耗尽、网络超时或解析器无法识别新响应而失败。这些事件都不能证明零件没有库存。
故障期间的运营目标是让系统诚实地展示“看不见”。可以用 MPNRadar查看监控记录，并参考API、聚合器还是网页比较不同来源方式。
先分类连接器事件
建议使用：
| 状态 | 含义 | 对库存的结论 |
|---|---|---|
| AUTH_FAILED | 密钥、令牌或账户认证失败 | 未知 |
| FORBIDDEN | 账户没有接口或产品权限 | 未知 |
| RATE_LIMITED | 因配额被拒绝或延迟 | 未知 |
| TIMEOUT | 请求在规定窗口内没有完成 | 未知 |
| HTTP_ERROR | 供应商返回错误响应 | 未知 |
| PARSE_FAILED | 响应到达但映射失败 | 未知 |
| STALE | 没有新鲜有效观测 | 未知 |
| HEALTHY | 获取并验证了有效观测 | 使用归一化结果 |
事件状态应和零件观测并列保存。健康连接器可以返回明确的缺货结果，坏掉的连接器不能。
第一步：检查认证和权限
确认：
- 环境和账户正确；
- 密钥或令牌没有过期；
- OAuth 或应用授权仍然有效；
- 请求使用正确的头部和端点；
- 账户有权访问目标产品和地区；
- 密钥来自批准的安全存储。
调试时不要把令牌输出到日志。可以记录经过脱敏的密钥标识、账户、端点和错误类别。DigiKey 的开发者文档描述了 OAuth、共同 API 原则、限流和状态码处理；具体流程仍以供应商当前文档为准。
第二步：在重试前检查限流
重复重试可能让小问题变成长时间阻断。记录：
- HTTP 状态和供应商错误码；
- 请求次数和时间窗口；
- 供应商提供的
Retry-After； - 连接器并发数；
- 重试退避策略；
- 下一次允许请求的时间。
DigiKey 的API 资源页面说明了限流和共同 API 原则。每个供应商的配额都应在连接器中单独配置，不能假设所有来源使用相同限制。
在符合供应商规则的情况下，可以使用带抖动的指数退避和最大等待时间。除非服务条款和内部公平规则允许，不要用大量密钥绕过供应商限制。
第三步：检查超时和网络
超时可能来自：
- DNS 或 TLS 问题；
- 供应商响应延迟；
- 查询或响应过大；
- 本地连接池耗尽；
- 代理或防火墙故障；
- 客户端超时短于供应商正常响应时间。
捕获持续时间、端点、地区、查询大小和重试次数，并区分供应商超时与客户端取消。如果只有一个地区失败，可使用受控健康检查进行比较；没有证据时，不要把所有供应结果都标成过期。
第四步：检查响应结构和解析
如果 HTTP 成功但解析失败，应保留受保护存储中的原始响应引用，并标记 PARSE_FAILED，不能默认数量为零。
检查：
- 字段缺失；
- 字段改名或嵌套层级变化；
- 空结果数组；
- 成功状态码中包含错误对象；
- 分页或部分响应标记；
- 单位、币种或地区名称变化。
Mouser 的API 文档描述了产品数据和购物车接口。HTTP 成功不代表监控所需的每个字段都存在，归一化前仍要做字段校验。
第五步：保护数据新鲜度
连接器故障时：
``text lastValidObservation = 带原始 observedAt 保留 currentConnectorState = 故障状态 displayedStockState = 过期或未知 nextAction = 修复并重新观测 ``
页面可以展示最后值作为上下文，但必须展示其年龄。未知库存不等于缺货详细说明了这个边界。
关键料号的响应策略
对于关键 MPN：
- 只在来源允许的策略内重试；
- 有第二个批准来源时进行对照；
- 创建带负责人与截止日期的运维事件；
- 保留带日期的最后一次有效观测；
- 新鲜度超过生产规则时升级给采购。
第二来源可以提供上下文，但不能修复失败的来源。来源专属事件仍应保留。
用证据关闭事件
关闭记录应包含：
- 根因类别；
- 首次与最后失败时间；
- 受影响的来源或 MPN；
- 代码、配置或密钥变化；
- 成功的测试请求；
- 恢复后的第一条新鲜观测；
- 期间错过的新鲜度窗口。
不要把观测时间回填成恢复时间。必须保留供应商数据真正被观测到的时间。
同时监控“监控器”
连接器健康应和产品信号分开统计：
| 指标 | 作用 |
|---|---|
| 成功率 | 判断请求是否返回有效响应 |
| 新鲜度年龄 | 判断最新有效观测有多旧 |
| 解析失败数 | 发现响应结构变化 |
| 限流响应数 | 发现配额压力 |
| 超时率 | 发现网络或供应商延迟 |
| MPN 覆盖率 | 判断监控清单有多少被实际检查 |
一次成功请求没有意义，如果关键 MPN 被跳过或响应不完整。
运维团队常问的问题
每种错误都应该重试吗？
不应该。网络瞬时错误可以在有上限的策略下重试。认证、权限和解析错误应先修复，再恢复批量请求。
可以把最后库存值展示成当前值吗？
不可以。应展示该值的时间和过期状态。只有重新获得有效的新鲜观测，当前值才是已知的。
第二个供应商 API 能替代所有故障吗？
如果 MPN、地区、封装和数量基础一致，它可以提供另一个信号；但不能证明第一个来源已经恢复，也不能证明两个供应商的字段语义相同。
最后检查
一套有用的 API 故障手册，应让操作人员知道哪里失败、哪些事实仍然有效、最后一次有效观测是什么时间、如何修复、何时需要采购介入。密钥不能进日志，故障要作为运维事件保留。
MPNRadar 用于整理监控证据，不保证供应商 API 可用或市场事实。修改连接器前请阅读供应商当前文档和账户条款。相关内容：归一化供应商库存、减少 BOM 误报、MPNRadar 定价。
Audience and limitations / 适用范围与限制
本文适用于需要监控电子元器件供应、采购和工程风险的团队。This article does not promise supplier accuracy, stock, price, delivery, lifecycle status, eligibility, approval, savings, or any specific business outcome. 具体决定仍应以当前来源、制造商资料、供应商条款和公司审批为准。