症状
API 返回 HTTP 429 Too Many Requests 响应，通常附带 Retry-After 头部指示等待时间。应用侧表现为：
- 批量请求中部分调用失败，返回限流错误。
- 日志中出现集中的 429 错误，且与请求峰值时段吻合。
- 用户感知为响应超时或功能间歇性不可用。
常见原因
- 瞬时并发过高：短时间内发起大量并行请求，超过供应商的每分钟请求数（RPM）或每分钟 Token 数（TPM）限制。
- 缺少请求队列：应用直接向 API 发起调用，未经过请求队列进行流量整形。
- 配额等级不匹配：使用的 API 密钥对应的配额等级较低，而业务增长已超出该等级的上限。
- 重试风暴：失败后立即重试且未引入退避策略，导致重试请求进一步加剧限流。
排查步骤
- 查看 API 响应头中的
x-ratelimit-remaining和x-ratelimit-reset字段，确认当前剩余配额和重置时间。 - 统计过去一小时内的请求频次分布，识别是否存在请求峰值与限流的时间关联。
- 检查应用代码中是否实现了指数退避重试（exponential backoff），首次重试间隔建议不低于 1 秒，最大退避时间设为 60 秒。
- 登录供应商控制台，确认当前 API 密钥的配额等级和已用量，评估是否需要申请提升配额。
- 在应用层引入请求队列（如 Redis 队列或内存信号量），将并发请求控制在配额范围内。
预防
- 在架构层面引入速率限制中间件，在请求到达 API 之前进行流量控制。
- 实现请求合并策略，将短时间内的多个相似请求合并为一次调用。
- 设置用量监控告警，当配额使用率达到 80% 时提前通知运维团队。
- 为不同业务模块分配独立的 API 密钥，隔离配额使用，避免单一模块耗尽全局配额。