LiteLLM 排错指南401、429 与超时报错如何快速定位【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm你刚把 LiteLLM 部署起来或者刚切换了模型服务商请求突然开始返回 401、429、超时先别急着翻配置——本文按 L1→L2→L3 三层给你一条排查动线覆盖最高频的AuthenticationError401 认证失败、RateLimitError429 限流和Timeout请求超时三类报错全部异常类的定义在 exceptions.py 里排不动时可以对照源码。报错第一反应打开 verbose读错误第一行所有 LiteLLM 异常都会把llm_provider、model、状态码写进消息体verbose 日志还会附上litellm_debug_info上游返回的原始错误细节。排错第一步不是改代码而是import litellm litellm.set_verbose True # 打开详细日志打开后复现一次请求看日志里第一行报错它是AuthenticationError还是RateLimitError直接决定你走下面哪一条路。代理服务器模式则在配置文件litellm_settings下取消注释set_verbose: True。查完记得关掉生产环境开着会刷爆日志。L130 秒能确认的硬伤401 / 404401 认证失败先查密钥尾部和环境变量名AuthenticationError就是服务商拒绝了你的密钥。按顺序做三件事printenv OPENAI_API_KEY | cat -A # 看密钥尾部有没有多余空格或换行第二件事是核对代理配置api_key: os.environ/OPENAI_API_KEY这种写法要求环境变量名逐字一致写错一个字母不会启动报错而是请求时才 401。第三件事才轮到怀疑密钥本身过期——这个坑挺常见但优先级要放最后。404 模型没找到两个高频原因NotFoundError404基本只来自两处model字段拼写错误或 provider 前缀缺失比如gpt-4o裸写没问题但gemini-2.5-flash必须写gemini/gemini-2.5-flash。先把你用的模型名拿去 model_prices_and_context_window.json 里搜一下搜不到就说明 LiteLLM 不认识这个写法换成带前缀的完整名再试。L1429 限流先看 category别猜是哪边在限RateLimitError429不只来自服务商——LiteLLM 代理自己也会限流并发请求数、预算、批处理配额等。区分方法直接读异常属性不用猜except litellm.RateLimitError as e: print(e.category) # vendor_rate_limit 还是 proxy 侧限制器 print(e.rate_limit_type) # 超的是次数、token 还是并发category是服务商限流给该部署加rpm配额、用 Router 挂多个部署做负载均衡是 proxy 侧限流调代理配置的并发/预算参数。两个方向改错地方会白忙一场。L2超时了先查什么Timeout默认 408 状态码分两种先区分再动手请求发出后一直没回包上游慢或网络断了还是流式中途断了stream_timeout生效。对应动作给部署加宽超时窗口长输出模型尤其要调stream_timeout给litellm_settings配重试和兜底模型把偶发慢请求消化掉litellm_settings: num_retries: 5 request_timeout: 600 context_window_fallbacks: - gpt-3.5-turbo: [gpt-3.5-turbo-large]如果调大超时也没用说明问题在链路代理到上游的网络这时才需要抓包或换api_base。L2上下文超限截历史还是换模型ContextWindowExceededError是BadRequestError的子类专指输入 token 超过模型上下文窗口。两个修复动作按成本排便宜截断或摘要对话历史多数场景能把 token 压回窗口内一劳永逸配context_window_fallbacks超限自动切到更大窗口的模型见上一节 yaml适合多轮对话产品。先算一下你的实际 token 数再决定别直接换旗舰大模型成本会上去。L3整个模型组都被打挂读 Router 的 cooldown 日志如果 429/超时集中爆发、所有部署轮流失败说明 Router 把部署逐个放进了 cooldown 冷却全部冷却时会抛RouterRateLimitError异常里直接带cooldown_list和冷却时长定位逻辑在 handle_error.py。这时看代理的 verbose 日志搜No deployment found for model和cooldown能确认是上游真挂了还是你自己的配额打满。同时建议接上 Prometheus / Langfuse 这类监控失败率曲线比逐条翻日志快得多速查卡报错现象第一反应关键配置/日志位置AuthenticationError401printenv \| cat -A查密钥尾字符代理配置api_key: os.environ/...一行NotFoundError404检查 provider 前缀和拼写model_prices_and_context_window.jsonRateLimitError429读e.category分清哪边限流部署的rpm、proxy 并发/预算参数Timeout超时区分整包无响应 vs 流中断timeout/stream_timeout/num_retries上下文超限截历史或配context_window_fallbackslitellm_settings.context_window_fallbacks全部署轮流失败搜日志cooldown看上游状态RouterRateLimitError.cooldown_list【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
