游戏 AI / 系统课时
处理超时重试与接口错误
处理超时重试与接口错误
NPC 对话接通模型后,玩家可能遇到长时间等待、请求超时、接口限流、鉴权失败或服务异常。直接把所有失败都显示成“网络错误”,会让玩家无法判断能否继续操作。本篇使用 Node.js 实现有限重试、整体超时和主动取消,并将不同异常映射成可读的 NPC 对话状态。
学习目标
- 区分超时、限流、鉴权失败、服务端错误及玩家主动取消,明确哪些情况可以重试。
- 配置单次请求超时、最多两次自动重试和整个对话的等待上限。
- 使用
AbortController取消未完成的调用,并把底层异常转换为可供游戏 UI 使用的状态。
按错误类型决定是否重试
LLM API 的失败结果不应该使用同一种处理方式。比如 HTTP 401 通常意味着服务端凭证错误,再试十次也不会恢复;HTTP 429 可能是暂时达到请求速率限制,等待后才有机会成功。
先建立一张处理表:
| 现象或状态 | 可能原因 | 是否重试 | 玩家看到的状态 |
|---|---|---|---|
| HTTP 401 | API Key 无效 | 否 | NPC 服务配置异常 |
| HTTP 403 | 项目或账号权限不足 | 否 | NPC 服务配置异常 |
| HTTP 429 | 速率限制或配额问题 | 有条件,有限次数 | NPC 正忙,请稍后再试 |
| HTTP 5xx | 上游服务暂时异常 | 是,有限次数 | NPC 服务暂时不可用 |
| 连接超时或临时网络故障 | 请求没有及时完成 | 是,有限次数 | NPC 响应超时或连接异常 |
| HTTP 400 | 请求参数不合法 | 否 | 本次请求无法处理 |
| 玩家主动取消 | 关闭对话、切换 NPC | 否 | 已取消本轮对话 |
一次重试不等于一次新的玩家操作。重试时应沿用同一轮输入,不重复追加聊天历史,不额外创建任务,也不要让客户端连续弹出多条相同错误提示。
OpenAI Node SDK 默认会对部分连接错误和 HTTP 408、409、429、5xx 响应进行最多两次自动重试。通过 maxRetries 可以修改或关闭这一行为。如果使用 SDK 的内置重试,就不要在外围再无条件添加一层同样的重试循环,否则实际请求次数会超出预期。
设计等待、截止时间与取消状态
游戏对话通常需要两层时间限制:单次网络调用不能无限等待,整个对话轮次也必须有总时间上限。只有单次超时而没有总体截止时间,自动重试可能让玩家等待远超预期。
本例采用以下参数:
| 参数 | 取值 | 含义 |
|---|---|---|
timeout |
4000 ms | 每次 SDK 请求尝试的超时设置 |
maxRetries |
2 | 初始尝试后最多自动重试两次 |
| 总等待上限 | 15000 ms | 包括调用、重试及等待时间 |
| 取消信号 | AbortController |
玩家主动结束当前对话轮次 |
因此一轮调用最多有三次请求尝试,但整个操作还受 15 秒截止时间约束。SDK 的实际退避等待会影响总时长,超过整体时间预算时直接取消剩余操作。

界面状态至少应区分 sending、success、timeout、rate_limited、config_error、service_error 和 cancelled。其中 sending 是正在等待,cancelled 表示玩家不再需要结果,不应弹出与服务器故障相同的错误提示。
当玩家切换到另一名 NPC、关闭对话框或离开场景时,当前请求就失去了展示对象。应立即触发取消,并在 UI 层使用轮次标识检查返回结果是否仍属于当前对话。
编写带错误分类的 NPC 调用器
使用 Node.js 20.3 或更新版本,在空目录中安装官方 SDK,并配置可用的环境变量 OPENAI_API_KEY。以下是 Bash 安装命令;其中密钥占位符必须替换为真实值。
npm init -y
npm install openai
export OPENAI_API_KEY='<YOUR_API_KEY>'预期结果:依赖安装完成,当前进程能够从环境变量中读取模型调用凭证。不要把真实密钥写入源文件或提交到版本控制系统。
创建 resilient-npc.mjs。代码使用 SDK 内置重试处理临时错误,用 AbortSignal.timeout() 设置整个轮次的截止时间,再通过 AbortSignal.any() 合并玩家取消和超时信号。
import OpenAI from 'openai';
const client = new OpenAI({
timeout: 4000,
maxRetries: 2
});
const cancel = new AbortController();
const deadline = AbortSignal.timeout(15000);
const signal = AbortSignal.any([cancel.signal, deadline]);
function readableError(error) {
// 玩家主动取消和总超时优先于底层网络错误分类。
if (cancel.signal.aborted) {
return { state: 'cancelled', message: '已取消本轮对话' };
}
if (deadline.aborted) {
return { state: 'timeout', message: '等待过久,请稍后再试' };
}
if (error instanceof OpenAI.AuthenticationError ||
error instanceof OpenAI.PermissionDeniedError) {
return { state: 'config_error', message: 'NPC 服务配置异常,请联系管理员' };
}
if (error instanceof OpenAI.RateLimitError) {
return { state: 'rate_limited', message: 'NPC 正忙,请稍后再试' };
}
if (error instanceof OpenAI.APIConnectionTimeoutError) {
return { state: 'timeout', message: 'NPC 响应超时,请重试' };
}
if (error instanceof OpenAI.APIConnectionError) {
return { state: 'network_error', message: '连接异常,请检查网络' };
}
if (error instanceof OpenAI.InternalServerError) {
return { state: 'service_error', message: 'NPC 服务暂时不可用' };
}
return { state: 'request_error', message: '本次请求无法处理' };
}
// 终端输入 cancel 模拟玩家关闭对话框时触发的取消事件。
process.stdin.setEncoding('utf8');
process.stdin.on('data', (line) => {
if (line.trim() === 'cancel') cancel.abort();
});
console.log('请求中;输入 cancel 后回车可取消');
try {
const response = await client.responses.create({
model: 'gpt-4.1-mini',
instructions: '你是城门守卫。用中文简短回复,不替玩家执行任何游戏操作。',
input: '城门什么时候关?',
max_output_tokens: 120
}, { signal });
const reply = response.output_text?.trim() || 'NPC 暂时没有台词';
console.log('success: ' + reply);
} catch (error) {
const result = readableError(error);
// 面向玩家只展示安全提示;详细错误与请求ID留给服务端日志。
console.log(result.state + ': ' + result.message);
} finally {
process.stdin.pause();
}这里的 timeout: 4000 是 SDK 调用尝试的超时配置,maxRetries: 2 表示允许的附加重试次数,不是总调用次数。AbortSignal.any() 会在玩家取消或整体截止时间到达时使组合信号进入中止状态。
错误分类安排在 SDK 重试结束之后,因此不会每次短暂失败都通知玩家。对于鉴权与权限错误,SDK 不会通过重复发送解决问题;对于网络连接异常、限流和服务端故障,则可能先执行允许的自动重试。
OpenAI.APIConnectionTimeoutError 与其他连接错误分别处理,是为了让玩家看到更准确的提示。服务端可以另外记录 HTTP 状态码、请求 ID 和重试次数,用于故障排查,但不应把包含内部细节的异常对象直接发送给游戏客户端。
运行并验证成功与取消
确保 OPENAI_API_KEY 已设置,在终端执行:
node resilient-npc.mjs预期输出(模型正常返回时):
请求中;输入 cancel 后回车可取消
success: <NPC_REPLY><NPC_REPLY> 代表模型实时生成的台词,内容并不固定。由于使用了真实 API,实际成功与否取决于网络、账户权限、模型可用性及请求时的服务状态。
再次运行,在请求尚未结束时输入 cancel 并按回车,预期输出为:
请求中;输入 cancel 后回车可取消
cancelled: 已取消本轮对话如果模型已经先一步返回成功,取消输入就不会再改变本轮结果。测试总超时时,应使用可控的延迟测试环境;不建议通过持续制造真实 API 故障来检验重试次数。
可以按以下条件检查异常处理:
- 有效凭证与网络:正常收到回复后,程序输出
success并退出等待。 - 主动取消:请求尚未完成时输入
cancel,程序输出cancelled,不会再进入新的 SDK 重试。 - 无效凭证:使用一个非空但无效的测试密钥时,若 API 返回 HTTP 401,程序输出
config_error,不继续重试;恢复正确密钥后再进行正常测试。 - 请求超时:单次尝试超过 4 秒时进入 SDK 超时处理;如果仍有重试机会且未超过总等待上限,可以再次尝试。
- 整体截止时间:总等待达到 15 秒时取消仍在进行的请求,向调用方返回超时状态。
- 限流或上游异常:可在单元测试中模拟 429、5xx 和连接错误,检查最大尝试次数以及最终的用户可读状态,而不是依赖线上随机故障。
将错误结果接入游戏对话界面
以上代码演示的是服务端调用器,实际游戏应让可信后端执行 SDK 请求,再向游戏客户端返回业务状态。不要把服务器的 API Key 或原始异常直接交给客户端。
UI 可以按状态执行以下操作:
| 业务状态 | 对话框行为 |
|---|---|
sending |
显示等待提示,暂时禁止重复提交 |
success |
更新 NPC 台词,解除等待 |
timeout |
显示“回应超时”,允许玩家主动重新发送 |
rate_limited |
显示“NPC 正忙”,进入适当冷却时间 |
config_error |
显示服务不可用,不鼓励玩家反复重试 |
network_error 或 service_error |
显示连接或服务故障,保留重新尝试入口 |
cancelled |
安静地关闭等待状态,不覆盖其他 NPC 的对话 |
在 Unity 中可以把取消动作接到关闭面板、退出交互或切换 NPC 的事件;在 Web UI 中可以使用 AbortController.abort() 取消 fetch。如果游戏客户端调用自己的后端,客户端中止 HTTP 请求后,后端还应通过连接断开或显式取消协议尽可能停止对应的上游工作。
最后为每轮对话分配一个独立的 requestId 或递增轮次编号。接收回复时先核对当前 NPC、当前轮次与界面是否仍然有效,核对失败就丢弃旧结果。这样即使服务器响应晚于玩家切换目标的操作,过期台词也不会错误地显示到新 NPC 的对话框中。