Skip to content

第 6 章:出错了怎么办 ​

本章目标:认识调用 API 时最常见的几种错误,分清哪些该重试、哪些该停下,并把 Key 从「每次 export」换成长期保存。

开篇:满屏红字 ​

前五章的周报生成器,每次都顺利跑完了。但你迟早会遇到这样的画面:周五下午,敲下命令,屏幕上滚出三四十行红色的报错,最后一行写着 openai.AuthenticationError。

这时候最需要知道两件事:是什么错?要不要再试一次? 有的错等几秒重试就好,有的错重试一百次也没用。

这一章我把常见错误挨个故意触发了一遍,看清它们的真面目。

学完这一章,你能:

  • 认出 401、400、402、429、5xx、超时、连不上这几类错误
  • 知道 SDK 已经替你重试了哪些,还需要自己处理哪些
  • 用 .env 文件长期保存 Key,并确保它不会被提交到 Git

6.1 把错误挨个触发一遍 ​

下面每一行都是真实触发出来的。「异常」一列是 Python 里捕获到的类型,「信息」是错误原文:

怎么触发的状态码异常信息(节选)
Key 写错401AuthenticationErrorAuthentication Fails, Your api key: ****0000 is invalid
模型名拼错(多打了一个 t)400BadRequestErrorThe supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek-chatt.
temperature=5400BadRequestErrorInvalid temperature value, the valid range of temperature is [0, 2]
超时设成 0.05 秒—APITimeoutErrorRequest timed out.
地址写错—APIConnectionErrorConnection error.

两点值得注意:

  • 错误信息写得很具体。模型名拼错时,它直接告诉你能用的是哪两个。遇到报错,先把最后几行读完,大部分时候答案就在里面
  • 有状态码的是服务器拒绝了你,没有状态码的是根本没连上(超时、断网)

还有几种我没法、也不该故意触发的,照 DeepSeek 官方错误码表补上:

状态码官方名称原因怎么办
402余额不足账户没钱了去充值
422参数错误请求参数不合法按错误信息改参数
429请求速率达到上限发得太快、太多放慢速度,稍后重试
500服务器故障服务端内部出错等一会儿重试
503服务器繁忙服务端负载高稍后重试

6.2 该重试的,和不该重试的 ​

把上面这些错误分成两类,判断方法只有一条:再发一次,结果会不会不一样?

好消息是,OpenAI 的 SDK 已经替你做了第一类。我翻了 SDK 源码,它的默认行为是:

设置默认值说明
max_retries2遇到超时、连不上、408、409、429、5xx,自动再试 2 次
重试间隔0.5 秒起,逐次加长,最多 8 秒越失败等越久,避免把服务器挤爆
timeout600 秒一次请求最多等 10 分钟

实测一下:超时设 0.05 秒,max_retries=0 时 0.1 秒就报错;用默认值时 1.5 秒才报错,中间它已经悄悄试了 3 次。

401、400 这类「你的问题」,SDK 不会重试,直接抛给你。

踩坑:默认超时是 10 分钟

网络卡住时,默认设置会让你的周报生成器干等 10 分钟才放弃。周报这种小请求,正常几秒就回来了,把 timeout 设成 60 秒足够。


6.3 周报生成器 v6:出错时说人话 ​

SDK 管了重试,我们要做的是:设一个合理的超时,再把最后还是失败的错误,翻译成看得懂的提示。

python
client = OpenAI(
    api_key=key,
    base_url="https://api.deepseek.com",
    timeout=60,       # 默认是 600 秒,周报等不了那么久
    max_retries=3,    # 网络抖动、429、5xx 自动重试(默认 2 次)
)

try:
    resp = client.chat.completions.create(...)   # 和上一章一样
except openai.AuthenticationError:
    sys.exit("Key 不对(401):检查 .env 里的 DEEPSEEK_API_KEY,或去开放平台重新创建一个")
except openai.APIStatusError as e:
    if e.status_code == 402:
        sys.exit("余额不足(402):去开放平台充值")
    sys.exit(f"请求被拒绝({e.status_code}):{e.message}")
except openai.APITimeoutError:
    sys.exit("超时:重试了 3 次还是没回应,稍后再试")
except openai.APIConnectionError:
    sys.exit("连不上 DeepSeek:检查网络或代理")

except 的顺序有讲究:AuthenticationError 是 APIStatusError 的一种,APITimeoutError 是 APIConnectionError 的一种,具体的要写在前面,否则会被宽泛的那条先接走。

把 Key 改错再跑,原来几十行的报错变成了一行:

text
Key 不对(401):检查 .env 里的 DEEPSEEK_API_KEY,或去开放平台重新创建一个

为什么不自己写重试循环

网上很多教程会教你写 for i in range(3): try: ... except: time.sleep(...)。SDK 已经内置了,而且做得更细:只重试该重试的错误、间隔逐次加长、还会参考服务器返回的「建议等多久」。自己再包一层,失败时反而要等「3 × 3」次。需要更多次时,调大 max_retries 就好。


6.4 Key 的长期保存:.env 文件 ​

第 1 章用 export 设环境变量,关掉终端就没了,每次都得重新设。长期用,把 Key 放进项目目录下的 .env 文件:

bash
pip install python-dotenv

在 weekly.py 同目录新建 .env,只写一行:

text
DEEPSEEK_API_KEY=sk-你的Key

代码开头加两行,它会把 .env 里的内容读进环境变量:

python
from dotenv import load_dotenv

load_dotenv()  # 把同目录 .env 里的 DEEPSEEK_API_KEY 读进环境变量

key = os.getenv("DEEPSEEK_API_KEY")
if not key:
    sys.exit("没找到 DEEPSEEK_API_KEY:在脚本同目录建一个 .env 文件,写上 DEEPSEEK_API_KEY=sk-...")

最关键的一步:同目录再建一个 .gitignore,写上:

text
.env

我在测试目录里 git init 之后 git add -A,确认 .env 没有被加进去,只加了 .gitignore、notes.md 和 weekly_v6.py。

踩坑:先 .gitignore,再 git add

顺序反了就晚了:.env 一旦被提交过,后来再写进 .gitignore 也删不掉历史里的那一份。万一已经推上 GitHub,别想着删提交,先去开放平台把这个 Key 删掉、换新的,这是唯一可靠的补救。


试一试 ​

  • [ ] 把 .env 里的 Key 改错一位,看看 v6 的提示
  • [ ] 把 timeout 改成 0.05,分别设 max_retries=0 和默认值,各跑一次,对比报错前等了多久
  • [ ] 在你的项目里 git status,确认 .env 不在列表里

本章小结 ​

要点说明
有状态码的错误服务器拒绝了你:401 Key、402 余额、400/422 参数、429 太快、5xx 服务端
没状态码的错误没连上:超时、断网、地址错
判断要不要重试再发一次结果会不会变:临时问题重试,你的问题停下
SDK 默认行为自动重试 2 次;超时 600 秒,记得改小
周报生成器 v6timeout=60、max_retries=3,失败时一行人话提示
Key 保存.env + python-dotenv;.gitignore 必须先写

下一章预告 ​

周报生成器已经很稳了,但它只认 DeepSeek 一家。哪天 DeepSeek 涨价、限流,或者公司要求用别家的模型,难道要重写?

不用。下一章用同一份代码切到别家模型,只改两行。

👉 第 7 章:换一家模型只改两行

本文阅读--次|全站访问--次|访客--人