Python 调大模型 API 五大坑,一次讲清楚

第一次把大模型 API 跑通，通常用不了几行代码。

也正因为太容易跑通，很多人会在这里产生一个误会：看到模型回话了，就以为自己已经会调 API 了。

真正麻烦的部分，往往要等你把代码放进循环里才出现。

一条请求没问题，几十条以后开始冒出 429；明明设了超时，程序却没有在你以为的时间点结束；有些错误重新运行几次自己好了，有些错误你重试十次还是原样回来。最容易让人抓狂的不是那串红字，而是你根本不知道：这次到底该等、该重试，还是该回去改代码？

所以这篇不打算再给你一段“复制就能用”的魔法代码。

我更想把一次模型调用拆开来看：请求是怎么发出去的，OpenAI Python SDK 默认替你做了哪些事，429、超时、400、鉴权失败分别意味着什么，以及哪些异常需要你自己接住。

看完以后，目标不是让你背住几种错误码，而是下次程序停在半路时，你能先判断一件事：这是一个值得重试的临时故障，还是一个必须改代码才能解决的确定性错误？

01先把最小调用跑通，但别急着庆祝

如果你现在第一次用 OpenAI Python SDK，最小调用可以写成这样：

from openai import OpenAIclient = OpenAI()  # 默认读取环境变量 OPENAI_API_KEYresponse = client.responses.create(    model="gpt-5.5",input="Python 里怎么用标准库读 CSV？",)print(response.output_text)

先别管模型回答了什么，单看这几行代码，其实只有三件事：

1. 构造客户端：OpenAI()。客户端负责鉴权、连接复用、默认重试和超时等底层行为。真实项目里建议复用同一个客户端，而不是每次请求都重新创建。
2. 发请求：client.responses.create(...)。你告诉服务端用哪个模型、输入什么内容。
3. 取结果：response.output_text。SDK 返回的是类型化响应对象，不是一个裸字符串；编辑器和静态类型检查工具因此能给你更多字段提示和类型帮助，但 Python 本身不会因为你写错类型提示就在“运行前自动拦截”。

如果你搜过旧教程，大概率还见过这种写法：

completion = client.chat.completions.create(    model="gpt-5.5",    messages=[        {"role": "user", "content": "Python 里怎么用标准库读 CSV？"},    ],)print(completion.choices[0].message.content)

这段不是“过期到不能用”。Chat Completions 仍然受支持，只是当前官方 SDK 已经把 Responses API 放在主要入口的位置。你看到 choices[0]，本质上只是因为 Chat Completions 的返回结构和 Responses API 不一样。

这里顺手提醒一个很实际的小问题：不要把 API Key 直接写死在准备提交到 GitHub 的代码里。 对第一次练习来说，把 Key 放进 OPENAI_API_KEY 环境变量，然后直接 OpenAI()，反而更省事，也少一次误传密钥的风险。

最小调用跑通以后，真正值得学的部分才开始。

02429：SDK 会替你重试，但别把它当无限续命

第一个高频错误是 429。

它通常和限流或配额有关。最迷惑人的地方在于：有时候你什么都没改，再跑一次，它自己又好了。于是很多人形成了一个习惯——看到 429 就手动再点一次运行。

其实 SDK 本身已经在做这件事。

OpenAI Python SDK 默认 max_retries=2。对于可重试错误，第一次失败以后还会再尝试两次，也就是一次调用最多可能发出 3 次尝试。

from openai import OpenAIclient = OpenAI(max_retries=2)

如果你明确不想让 SDK 自动重试，可以关掉：

client = OpenAI(max_retries=0)

对本地 mock 端点连续注入 429，两种配置的差异很直观：

这里真正需要记住的不是“2”这个数字，而是：SDK 的重试发生在单次 API 调用内部。

如果你外面还有一个处理 1000 条文本的循环，最坏情况下，每一条都可能经历多次尝试。于是你以为自己只写了 1000 次调用，真实发出的请求数量却可能高得多。

这也是为什么批量任务不能只依赖 SDK 内置重试。SDK 能替你处理一次请求里的短暂波动，但它不知道你的整个任务应该跑多快。持续撞 429 时，真正该看的往往是调用频率、并发数、配额和任务级调度，而不是继续给 max_retries 加数字。

还有一个原稿里很容易说反的细节：当前 SDK 并不是完全无视服务端的等待提示。实现里会读取 retry-after-ms / Retry-After；在合理范围内，会优先按服务端给出的等待时间处理，否则再走带抖动的指数退避。

所以，看到 429 后最不该做的事，是再在 SDK 外面随手套一层没有边界的 while True: retry()。

03超时：你设的是“一次尝试怎么等”，不是整个任务的秒表

第二个最常见的误会是超时。

很多人第一次看到 timeout，会自然理解成：“我设 30 秒，那么这次调用 30 秒以后一定结束。”

事情没这么简单。

OpenAI Python SDK 当前默认请求超时是 10 分钟，不是 10 秒。你当然可以自己改：

from openai import OpenAIclient = OpenAI(    timeout=30.0,    max_retries=2,)

也可以只给某一次请求单独改：

response = client.with_options(timeout=5.0).responses.create(    model="gpt-5.5",input="hi",)

对本地 mock 端点做“服务端延迟 3 秒、客户端 timeout=1.0”的测试时，SDK 会抛出 APITimeoutError。这个错误的重点在于：是客户端决定不再继续等，而不是服务端返回了一个‘我超时了’的业务错误。

更容易忽略的是，超时本身也属于默认会重试的情况。

也就是说，如果 max_retries=2，第一次等到超时以后，SDK 还可能再发起两次尝试，中间再叠加退避等待。所以 timeout=30 并不等于“整个函数最多 30 秒返回”。

更准确的理解是：

timeout 管一次尝试怎么等，retry 管这次尝试失败以后还要不要再来。

这两个参数是绑在一起看的。

如果你做的是交互式产品，用户不可能接受一次请求卡几分钟，那么就应该主动把 timeout 设得更符合产品预期；如果你做的是离线批处理，容忍度又会完全不同。SDK 不知道你的业务场景，所以这里没有一个“全行业最佳数字”。

04400：这种错误别重试，先去看自己发了什么

和 429、连接错误、超时不同，400 Bad Request 通常说明请求本身有问题。

比如字段格式不对、参数组合非法、请求体不符合接口要求。这类错误最重要的特征是：同样的请求再发十遍，大概率还是错。

SDK 因此不会默认替你重试 400，而是直接抛出 BadRequestError。

对本地 mock 端点注入一个 400，可以看到它立即进入异常分支，没有像 429 那样继续尝试。

你可以把常见错误先按“下一步该干什么”来分，而不是背一串状态码：

429 / 超时 / 连接故障        ↓可能是暂时的        ↓考虑退避、重试、限速400 / 401        ↓请求或凭证本身有问题        ↓先改参数、检查 Key / 权限

其中 401 对应 AuthenticationError。它和 429 看起来都属于“API 报错”，但处理方向完全相反：一个该检查 Key 和权限，一个该看频率和配额。

这也是我觉得错误处理里最值得形成的习惯：先判断这个错误有没有可能“等一等自己变好”。

如果答案是否定的，就别浪费时间重试。

05异常别只会写一个 except Exception

SDK 的异常有继承关系，但第一次调用 API 没必要把整棵树都背下来。

先抓住几类就够了：

RateLimitError ─┐                ├─→ APIStatusError → APIError → OpenAIErrorBadRequestError ┘APITimeoutError ─→ APIConnectionError → APIError → OpenAIError

落到代码里，可以这样分：

from openai import (    OpenAI,    OpenAIError,    RateLimitError,    APITimeoutError,    BadRequestError,    AuthenticationError,)client = OpenAI()try:    response = client.responses.create(        model="gpt-5.5",input="用一句话解释什么是 API 限流",    )except RateLimitError:# 限流：SDK 已经按当前重试策略尝试过    ...except APITimeoutError:# 一次或多次请求等待超时    ...except BadRequestError:# 请求本身有问题，继续原样重试没有意义    ...except AuthenticationError:# Key / 权限问题    ...except OpenAIError:# 其他 SDK 层错误    ...

这样写的好处不是“代码更专业”，而是排错的时候不用猜。

日志里看到 AuthenticationError，就去看 Key；看到 RateLimitError，就别再怀疑 JSON 格式；看到 BadRequestError，也别坐在那里等一分钟再重试。

错误类型本身，就是排查方向。

06兼容端点还有一层坑：别假设所有异常都会被 SDK 包好

如果你只访问官方端点，服务端响应会遵循官方契约。

但现实里很多人还会通过代理、网关、自建服务，或者所谓“OpenAI 兼容接口”接模型。这时候会多一层麻烦：接口长得像 OpenAI，不代表每个响应细节都和官方一致。

本文对本地 mock 兼容端点注入过一个“HTTP 成功，但响应体不是合法 JSON”的场景。在这条测试路径里，Python 原生的 json.JSONDecodeError 会直接冒出来，并不属于 OpenAIError。

这个结果不应该扩大解释成“官方 OpenAI API 经常会返回坏 JSON”。它真正提醒的是另一件事：

如果你接的是兼容网关，不要把 except OpenAIError 当成宇宙级兜底。

尤其在流式响应、代理改写响应体、自建兼容层这些场景里，还可能出现 SDK 异常体系之外的解析错误。

所以这类项目里，最好把“官方 SDK 错误”和“外围协议 / 解析错误”分开记录。出了问题以后，你才能知道到底是模型服务没回，还是中间那层网关把响应弄坏了。

07把它拼成一份真正能改的最小脚本

前面的知识如果不落到代码里，很快又会变成“我好像看懂了”。

下面这份骨架我更建议第一次调 API 的人保存下来：

import jsonfrom openai import (    OpenAI,    OpenAIError,    RateLimitError,    APITimeoutError,    BadRequestError,    AuthenticationError,)client = OpenAI(    timeout=30.0,    max_retries=2,)def ask(model: str, user_prompt: str) -> str:try:        response = client.responses.create(            model=model,input=user_prompt,        )return response.output_textexcept RateLimitError:print("限流：检查请求频率、并发和配额")raiseexcept APITimeoutError:print("超时：检查网络、服务端响应速度和 timeout 配置")raiseexcept BadRequestError:print("请求参数有问题：继续原样重试没有意义")raiseexcept AuthenticationError:print("鉴权失败：检查 API Key 和权限")raiseexcept json.JSONDecodeError:print("响应不是合法 JSON：如果用了代理或兼容端点，优先检查中间层")raiseexcept OpenAIError as e:print("其他 OpenAI SDK 错误：", e)raiseprint(ask("gpt-5.5", "用一句话解释什么是 API 限流"))

这里我特意没有把异常变成“限流了”“超时了”这样的普通字符串返回。

原因很简单：如果 ask() 的正常返回值也是字符串，那么你把错误信息也当字符串返回，后面的代码很容易把“限流了”当成模型答案继续写进数据库、CSV 或报表。小 demo 看不出问题，一跑批量任务就会留下很脏的数据。

更稳妥的做法是：这一层负责识别和记录错误，是否跳过、重试、降级，交给外面的任务逻辑决定。

这也是从“示例代码”走向“能长期跑的代码”时，一个很小但很重要的分界线。

08真正学会调 API，是失败以后知道下一步做什么

第一次调用成功，其实最容易。

几行代码、一个 Key、一个模型名，看到终端里吐出第一段回答，那一刻确实很有成就感。但只要你开始批量跑数据，就会发现真正消耗时间的从来不是 client.responses.create() 这一行。

而是它失败以后，你接下来怎么办。

429 来了，是不是要立刻重跑？

请求卡住了，timeout 到底限制了什么？

400 连续出现，是网络不好，还是自己参数写错了？

SDK 已经重试过几次了？外层还要不要再套一层重试？

如果接了一个兼容网关，报错到底来自 OpenAI SDK，还是中间那层服务？

这些问题能回答清楚以后，API 调用才算真正从“能跑”变成了“可控”。

你甚至不需要记住整篇文章。

先记住四件事就够了：

• 第一，SDK 默认会替一部分临时错误重试，但不是所有错误都值得重试。
• 第二，timeout 和 retry 是两件事：一个管单次等待，一个管失败以后还试不试。
• 第三，400、401 这种确定性错误，先改请求和凭证，别靠重跑碰运气。
• 第四，批量任务的可靠性不能全部甩给 SDK，最终的限速、失败记录、跳过还是终止，要由你的业务逻辑决定。

所以下次再遇到“跑到第 17 条突然挂了”，先别删掉重跑。

看一眼异常类型，再看一眼自己的重试和超时配置。

当你能从那串红字里直接判断下一步该做什么时，这套 API 才算真正用顺手了。