API Integration Is Unstable（API 集成不稳定）

知识库位置：FDE Knowledge Base/03 Engineering/Troubleshooting/API-Integration-Is-Unstable.md

Problem（问题）

调用客户或第三方 API（Application Programming Interface，应用程序编程接口）时，经常：

Timeout（超时）
5xx（服务端错误）
Connection Reset（连接重置）
Rate Limit（限流）
Authentication Failure（认证失败）

First Question（第一个问题）

先判断：

是我们的系统有问题，还是 Dependency（依赖）有问题？

Diagnostic Dimensions（诊断维度）

Availability（可用性）

API 是否整体不可用？

Latency（延迟）

只是变慢？

Error Rate（错误率）

错误比例是多少？

Endpoint Specific（特定端点）

所有 Endpoint（接口端点）都失败，还是某一个？

Authentication（认证）

Token（令牌）是否过期？

Rate Limit（限流）

是否超过限制？

Diagnostic Flow（诊断流程）

API Failure（接口失败）
↓
Network reachable?（网络可达吗）
↓
Authentication valid?（认证有效吗）
↓
Request valid?（请求合法吗）
↓
Rate limit?（被限流了吗）
↓
Dependency 5xx?（依赖端服务错误吗）
↓
Timeout?（超时了吗）

Fixes（修复）

Timeout（超时）

每个外部调用必须有合理 Timeout。

Retry（重试）

只 Retry：

429（请求过多）
部分 5xx（服务端错误）
Temporary Network Failure（临时网络故障）

Backoff（退避）

例如：

1s → 2s → 4s → 8s（1 秒 → 2 秒 → 4 秒 → 8 秒）

Circuit Breaker（熔断器）

依赖持续失败时：

暂停继续打流量。

Cache（缓存）

查询类 API 可考虑短时 Cache。

Queue（队列）

非即时操作可以转为异步。

Anti-pattern（反模式）

不要：

while failed:
    retry()（失败就一直重试）

无限 Retry 会放大故障。

Prevention（预防）

监控：

API Latency（接口延迟）
Error Rate（错误率）
429 Rate（限流比例）
Timeout Rate（超时比例）

并针对 Dependency（依赖）建立独立 Dashboard（监控面板）。