[Bug]: With BYOK, one client’s 429 cools the shared deployment for everyone for the provider’s full retry-after, and the cooldown can’t be c

快速结论：该问题通常出现在 LiteLLM Proxy 开启 BYOK（general_settings.forward_llm_provider_auth_headers: true）后：某个客户端自带凭证被上游返回 429，路由器把这次失败记到共享 deployment 上，并按 provider 的 retry-after 冷却整个 deployment，导致其他凭证正常的客户端也被拒绝。优先排查 deployment 级 cooldown 是否被错误触发、是否被 Redis 与 worker 内存双重缓存、以及是否可通过 cooldown_time: 0 规避。

适用环境：Issue 已确认 LiteLLM Proxy v1.104.1，配置了 general_settings.forward_llm_provider_auth_headers: true、allowed_fails_policy.RateLimitErrorAllowedFails: 1，上游为 Anthropic，且配置了 Redis；操作系统、Python、CUDA、显卡等信息 Issue 未提供。

最快修复方案：Issue 中验证可用的规避方式是在对应 deployment 的 model_info 中设置 cooldown_time: 0，关闭该 deployment 的冷却；若已进入冷却，Issue 中验证有效的清理方式为删除 deployment:*:cooldown 键后再重启 proxy。根因修复需升级到包含相关修复的 LiteLLM 版本（合并 PR 为 #48485）。

注意事项：cooldown_time: 0 会关闭该 deployment 的所有冷却，真实的上游故障也不会触发保护性冷却；retry-after 驱动冷却长度这一点在原文档中未被说明。只重启 proxy 或只删 Redis 键都不能及时清除冷却，必须两件事配合完成。若版本中已包含 upstream Retry-After 冷却上限的修复，超长冷却会被截断，但具体默认上限请以所装版本实现为准。

问题场景

在 LiteLLM Proxy 上启用 BYOK（Bring Your Own Key），通过 forward_llm_provider_auth_headers: true 转发客户端自带的 provider 凭证。多个客户端共用同一个 model/deployment，但各自使用自己的 Anthropic 订阅或 key。当其中一个客户端的订阅额度用尽、请求被 Anthropic 以 429 拒绝时，该 429 被路由器记录为 deployment 失败；在 RateLimitErrorAllowedFails: 1 下，第二次 429 即触发 deployment 冷却，冷却时长取自 provider 的 retry-after。Issue 报告在 1.104.1 生产环境中，一个 claude-opus deployment 被置为 168,307 秒（约 47 小时）冷却，期间所有客户端请求都被拒绝；若配置了 fallback，流量在整个冷却期内被转移到 fallback provider。

报错原文

[Bug]: With BYOK, one client's 429 cools the shared deployment for everyone for the provider's full retry-after, and the cooldown can't be cleared

原因分析

这是多租户隔离缺口。可能原因与已确认机制如下：

路由器的冷却状态以全局 deployment_id 为键（deployment:<model_id>:cooldown），而不是以引发错误的客户端凭证为键，因此单个租户的 429 会冷却整个共享 deployment。
BYOK 下一客户端 429 通常表示该客户端自己的订阅或 key 达到上限，并不代表 deployment 不可用，但路由器仍按 deployment 失败处理。
当 deployment 未设置 cooldown_time 时，冷却时长直接取自 provider 的 retry-after 响应头且无上限（router.py 约 L8190、utils.py::_get_retry_after_from_exception_header）。按日封顶的订阅会返回很长的 retry-after。
冷却同时存在于 Redis 和各 worker 的内存缓存中，且互不同步：重启 proxy 时 worker 会从 Redis 读回冷却；只删 Redis 键时任然持有内存副本的 worker 不会重新读取，从 Redis 回填的副本沿用 InMemoryCache 默认 600 秒 TTL（DualCache._backfill_kwargs），记录冷却的 worker 则保留完整 TTL。
没有列出或清除冷却的接口，只能手工删键。

环境排查

确认 LiteLLM Proxy 版本（Issue 为 v1.104.1）及是否已包含 PR #48485 的修复。
确认 general_settings.forward_llm_provider_auth_headers 是否为 true，即是否处于 BYOK 多客户端共用 deployment 的场景。
确认 router_settings.allowed_fails_policy 中 RateLimitErrorAllowedFails 的取值。
确认对应 deployment 的 model_info 是否设置了 cooldown_time，以及是否配置了 router_settings.max_cooldown_time。
确认是否配置 Redis，以及 Redis 中是否存在 deployment:*:cooldown 键。
确认 model group 是否配置了 fallback（会影响故障影响面）。
Issue 未提供操作系统、Python、依赖版本信息，这些项目无需据此排查。

解决步骤

先止血：在 redis-cli 中执行 redis-cli --scan --pattern 'deployment:*:cooldown' | xargs -r redis-cli DEL 删除冷却键，然后重启 LiteLLM Proxy。仅执行其中一步不会及时生效。

在受影响的 deployment 的 model_info 中设置 cooldown_time: 0，关闭该 deployment 的冷却。该值优先于 retry-after，且 0 会被正确采纳。示例：

model_list:
  - model_name: claude-haiku-5-5
    litellm_params:
      model: anthropic/claude-haiku-5-5
      api_key: os.environ/ANTHROPIC_API_KEY
    model_info:
      cooldown_time: 0

可优先尝试：在 router_settings 中设置 max_cooldown_time，为上游 Retry-After 驱动的冷却设置上限，避免出现分钟级乃至天级锁定。该参数的具体行为以所装版本文档与代码为准。
升级到包含 PR #48485 修复的 LiteLLM 版本。该修复将客户端凭证头（x-api-key、Authorization、api-key 等）识别为客户端侧凭证，BYOK 请求使用隔离的动态凭证 ID；在 BYOK 凭证触发 429 时跳过 deployment 冷却并将 429 直接返回调用方；同时对上游 Retry-After 冷却按 Router.max_cooldown_time 或默认上限（3600 秒）截断。

验证方法

用配置好的 proxy 让一个客户端（其自身 Anthropic 订阅已封顶）连续发送两次请求触发 429，再立即用另一个凭证正常的客户端请求同一 model。若后者仍能正常返回、未出现拒绝，且 Redis 中不再生成针对共享 deployment 的冷却键，说明冷却已正确隔离。同时可检查重启后冷却是否仍从 Redis 回填并继续生效，以确认清理与配置均已到位。