第 6 章:出错了怎么办
本章目标:认识调用 API 时最常见的几种错误,分清哪些该重试、哪些该停下,并把 Key 从「每次 export」换成长期保存。
开篇:满屏红字
前五章的周报生成器,每次都顺利跑完了。但你迟早会遇到这样的画面:周五下午,敲下命令,屏幕上滚出三四十行红色的报错,最后一行写着 openai.AuthenticationError。
这时候最需要知道两件事:是什么错?要不要再试一次? 有的错等几秒重试就好,有的错重试一百次也没用。
这一章我把常见错误挨个故意触发了一遍,看清它们的真面目。
学完这一章,你能:
- 认出 401、400、402、429、5xx、超时、连不上这几类错误
- 知道 SDK 已经替你重试了哪些,还需要自己处理哪些
- 用
.env文件长期保存 Key,并确保它不会被提交到 Git
6.1 把错误挨个触发一遍
下面每一行都是真实触发出来的。「异常」一列是 Python 里捕获到的类型,「信息」是错误原文:
| 怎么触发的 | 状态码 | 异常 | 信息(节选) |
|---|---|---|---|
| Key 写错 | 401 | AuthenticationError | Authentication Fails, Your api key: ****0000 is invalid |
| 模型名拼错(多打了一个 t) | 400 | BadRequestError | The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek-chatt. |
temperature=5 | 400 | BadRequestError | Invalid temperature value, the valid range of temperature is [0, 2] |
| 超时设成 0.05 秒 | — | APITimeoutError | Request timed out. |
| 地址写错 | — | APIConnectionError | Connection error. |
两点值得注意:
- 错误信息写得很具体。模型名拼错时,它直接告诉你能用的是哪两个。遇到报错,先把最后几行读完,大部分时候答案就在里面
- 有状态码的是服务器拒绝了你,没有状态码的是根本没连上(超时、断网)
还有几种我没法、也不该故意触发的,照 DeepSeek 官方错误码表补上:
| 状态码 | 官方名称 | 原因 | 怎么办 |
|---|---|---|---|
| 402 | 余额不足 | 账户没钱了 | 去充值 |
| 422 | 参数错误 | 请求参数不合法 | 按错误信息改参数 |
| 429 | 请求速率达到上限 | 发得太快、太多 | 放慢速度,稍后重试 |
| 500 | 服务器故障 | 服务端内部出错 | 等一会儿重试 |
| 503 | 服务器繁忙 | 服务端负载高 | 稍后重试 |
6.2 该重试的,和不该重试的
把上面这些错误分成两类,判断方法只有一条:再发一次,结果会不会不一样?
好消息是,OpenAI 的 SDK 已经替你做了第一类。我翻了 SDK 源码,它的默认行为是:
| 设置 | 默认值 | 说明 |
|---|---|---|
max_retries | 2 | 遇到超时、连不上、408、409、429、5xx,自动再试 2 次 |
| 重试间隔 | 0.5 秒起,逐次加长,最多 8 秒 | 越失败等越久,避免把服务器挤爆 |
timeout | 600 秒 | 一次请求最多等 10 分钟 |
实测一下:超时设 0.05 秒,max_retries=0 时 0.1 秒就报错;用默认值时 1.5 秒才报错,中间它已经悄悄试了 3 次。
401、400 这类「你的问题」,SDK 不会重试,直接抛给你。
踩坑:默认超时是 10 分钟
网络卡住时,默认设置会让你的周报生成器干等 10 分钟才放弃。周报这种小请求,正常几秒就回来了,把 timeout 设成 60 秒足够。
6.3 周报生成器 v6:出错时说人话
SDK 管了重试,我们要做的是:设一个合理的超时,再把最后还是失败的错误,翻译成看得懂的提示。
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 改错再跑,原来几十行的报错变成了一行:
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 文件:
pip install python-dotenv在 weekly.py 同目录新建 .env,只写一行:
DEEPSEEK_API_KEY=sk-你的Key代码开头加两行,它会把 .env 里的内容读进环境变量:
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,写上:
.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 秒,记得改小 |
| 周报生成器 v6 | timeout=60、max_retries=3,失败时一行人话提示 |
| Key 保存 | .env + python-dotenv;.gitignore 必须先写 |
下一章预告
周报生成器已经很稳了,但它只认 DeepSeek 一家。哪天 DeepSeek 涨价、限流,或者公司要求用别家的模型,难道要重写?
不用。下一章用同一份代码切到别家模型,只改两行。