[Bug]: No Retry-After header on RouterRateLimitError (all deployments in cooldown)

快速结论：当 LiteLLM 代理中某个模型的全部上游部署因触发限流（429）而进入冷却（cooldown）时，LiteLLM 会抛出 RouterRateLimitError，但其 HTTP 响应中缺少 Retry-After 头部。优先排查方法：手动捕获 RouterRateLimitError 并解析其 cooldown_time 属性，或等待上游补丁（#27823）修复。

问题场景

用户在运行 LiteLLM Proxy 时，当某个模型的所有上游部署（如 z.ai 的 GLM-5.1）同时因为上游返回 429 错误触发冷却机制后，LiteLLM 直接返回 429 响应（RouterRateLimitError），但响应中不包含标准的 Retry-After HTTP 头。这导致下游客户端（OpenAI SDK、自定义客户端、网关代理）无法通过标准方式获知重试时机，只能解析错误消息体中的字符串来获取等待秒数。

报错原文

HTTP/1.1 429 Too Many Requests
content-type: application/json
x-litellm-call-id: ...
x-litellm-version: ...

{"error": {"message": "No deployments available for selected model, Try again in 60 seconds. ...", "type": "None", "param": "None", "code": "429"}}

原因分析

在 litellm/proxy/common_request_processing.py 的 _handle_llm_api_exception 函数中，当组装 HTTP 响应头（headers）并准备抛出 ProxyException 之前，没有检查异常类型是否为 RouterRateLimitError。该异常类本身带有 cooldown_time 浮点属性，但在构造响应时未将其转换为 Retry-After HTTP 头。这是 LiteLLM 自身作为限流器（路由级别冷却）的场景，与转发上游提供商的 Retry-After 头部（#21553）或从提供商消息中暴露 retry_after 属性（#26070）是不同的问题。

环境排查

确认 LiteLLM 版本：Issue 中报告的是 1.83.0
确认部署方式：LiteLLM Proxy
确认上游提供商配置：z.ai (GLM-5.1) 或其他可能触发 cooldown 的提供商

解决步骤

临时方案（客户端侧）：在客户端代码中捕获 RouterRateLimitError，如果捕获到，从错误消息体中提取等待秒数（例如通过正则解析 “Try again in X seconds”），然后自行实现重试逻辑。
永久方案（等待上游补丁）：该 Issue 已修复（关闭于 2026-06-12），修复位置在 litellm/proxy/common_request_processing.py 的 _handle_llm_api_exception 函数。修复逻辑为：在组装 headers 后、抛出 ProxyException 之前，检查异常是否为 RouterRateLimitError；如果是，则获取其 cooldown_time 属性并添加到 headers 中：headers["retry-after"] = str(int(cooldown_time))。建议升级到包含该修复的 LiteLLM 版本。
替代方案（可优先尝试）：如果无法升级，可以在 LiteLLM 代理上层部署带有自我修复能力的中介层，例如 NeuralBridge SDK（评论中提及的一种方案），它能够主动检测冷却状态并将流量重新路由到健康的部署，而不是依赖 Retry-After 头部。

验证方法

在应用修复或升级后，当所有部署再次进入冷却状态时，通过 curl 或客户端工具检查返回的 HTTP 响应头，确认是否包含类似 Retry-After: 60 的头部。如果包含，则表示问题已解决；否则需要检查是否使用了正确版本或补丁是否生效。

参考来源

BerriAI/litellm #27823

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: No Retry-After header on RouterRateLimitError (all deployments in cooldown)