n8n 工作流失败时，画布上通常只有一行红色提示。真正有用的信息藏在执行记录里：HTTP 状态码、上游返回的 error code、请求实际发到了哪个地址。把这三样拿到，大多数报错能在几分钟内定位。

本文按错误类型拆开讲：401 和 403 属于凭证与权限，404 多半是 Base URL 或模型名，429 是限流与配额，节点超时和工作流失败则要看配置与运行环境，最后是 JSON 解析失败。文末给出一套固定的排查顺序，方便团队写成自己的 runbook。

说明：n8n、OpenAI 分别为其权利人的商标，本文与相关厂商无隶属关系；模型名称与价格以站内 模型价格 为准，节点字段以你当前使用的版本为准。

一、先看执行记录，不要猜

打开左侧的 Executions，筛选 Failed，点进失败的那次执行，逐个节点看输入、输出和错误详情。需要重点记录四项：节点名称、HTTP 状态码、上游 error code、请求 ID（如果有）。这四项决定了问题是出在 n8n 配置、网络链路还是上游服务。

常见状态码可以先按这张表粗分：

状态码 常见含义 先查什么
401 未认证或 Key 无效 凭证是否选中、Key 是否过期
403 已认证但无权限 模型权限、IP 白名单
404 地址或模型不存在 Base URL 路径、模型名拼写
429 限流或配额耗尽 并发数、重试策略、账户额度
400 请求参数不合法 字段名、上下文长度、消息格式
5xx 上游临时故障 稍后重试、查看服务状态页

二、401：Key 正确也可能失败

401 不总是“Key 填错了”。常见原因还有：凭证创建后未在工作流节点里选中；复制时带入了空格或换行；测试 Key 被停用；团队里多人共用实例，节点引用的是另一套凭证；自部署实例更换了 N8N_ENCRYPTION_KEY，旧凭证无法解密。

处理顺序很简单：重新选择一次凭证，重新粘贴 Key，保存后单独执行该节点。如果仍失败，在能代表 n8n 运行环境的机器上跑一次 curl：

curl -i https://你的网关地址/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型名","messages":[{"role":"user","content":"只回复 OK"}]}'

curl 成功而 n8n 失败，问题在凭证或节点配置；两边都失败，问题在 Key、网关或网络。不要把 Key 写进 Code 节点、工作流 JSON 或备注字段，这些都容易被导出和共享。

三、404：Base URL 与模型名各占一半

OpenAI 类型凭证里的 Base URL 通常填到 /v1 为止，节点会自己拼接 /chat/completions。多写一段完整路径，就会出现 /v1/chat/completions/chat/completions 这类地址，返回 404。反过来，HTTP Request 节点需要完整 URL，不能只填域名。

另一半 404 来自模型名。OpenAI 兼容服务常用 model_not_found 表示模型不存在，它可能返回 404，也可能包在 400 里。核对三件事：模型名大小写、是否带了日期后缀、网关上是别名还是上游原名。最稳妥的办法是请求 /v1/models，只使用返回列表里存在的名字。

还有几个细节：Base URL 末尾多写斜杠可能产生双斜杠；网关挂在反向代理的子路径下时，前缀不能省；切换测试和生产环境后，地址没有同步修改。

四、429：限流不能只靠重试硬扛

429 表示请求被限流，常见触发条件有三类：每分钟请求数或 Token 数超限、并发数超限、账户配额或余额不足。响应头里的 Retry-After 如果有值，应优先遵守，而不是立刻重发。

n8n 节点设置里可以开启 Retry On Fail，把最大尝试次数设为 2 到 3 次，并设置递增的等待时间。但重试只能消化短时抖动，不能解决持续超限。批量任务要降低并发，用 Split In Batches 或 Loop Over Items 分批处理，批次之间留出间隔；定时任务尽量错峰；调试时不要直接对全量数据执行。

五、节点超时与工作流失败

超时要先分清层级：HTTP Request 节点自身的超时、工作流级别的超时、反向代理或负载均衡的超时、上游模型生成耗时。任何一层先到点，执行都会失败，错误信息里的措辞通常不同。

长文本生成容易超过默认限制。可以适度调大节点超时，同时压缩输入、限制最大输出、把任务拆小。不要让工作流无限等待，也不要把超时设得大到故障时长时间占住执行槽。自部署实例还要检查进程是否被重启、队列模式下的 worker 是否在线。

节点级失败策略也要配置：批处理任务用 On Error 继续执行并保留错误项，关键写入节点选择停止工作流；再配置一个 Error Workflow，把执行 ID、节点名和输入摘要发到群聊或邮箱。失败不可怕，没有记录才可怕。

六、JSON 解析失败：模型输出不是 JSON

典型报错是 JSON parameter needs to be valid JSON，或者 Code 节点里的 JSON.parse 抛异常。原因通常是模型在 JSON 外面加了说明文字或 Markdown 代码围栏，字段类型也和约定不一致。

先在上游解决：提示词明确“只输出 JSON，不要代码块”，字段和类型写清楚；网关或模型支持结构化输出时优先使用。下游仍要防御性解析，例如在 Code 节点里：

const raw = $json.text ?? $json.content ?? "";
const cleaned = String(raw)
  .replace(/^```(?:json)?\s*/i, "")
  .replace(/```\s*$/, "")
  .trim();

try {
  return [{ json: JSON.parse(cleaned) }];
} catch (e) {
  return [{ json: { parse_error: true, raw: cleaned } }];
}

解析失败时不要静默丢弃，把原文写入异常表，人工抽查几条，往往能发现提示词或模型能力的问题。

七、一套可复用的排查顺序

  1. 确认影响范围：单条记录失败，还是整批、整个工作流都失败。
  2. 在 n8n 同网络环境用 curl 复现，排除节点配置干扰。
  3. 对比 n8n 实际请求的 URL、请求头和请求体，重点看 Base URL 拼接。
  4. 请求 /v1/models 核对模型名，确认大小写和后缀。
  5. 记录状态码与 error code：401、403、404 不重试，429、5xx、超时才有重试价值。
  6. 检查超时、并发和批次大小，再决定是否调整重试参数。
  7. 把结论写进团队 runbook，附上错误样例和修复动作。

常见问题

n8n 里报 401，但 curl 请求正常，问题在哪？

优先检查节点引用的凭证是否选错、Key 是否多了空格或换行、实例是否更换过加密密钥。也可以在 HTTP Request 节点里手动加 Authorization 头做对比，确认问题出在凭证解析还是请求构造。

404 一定是 Base URL 写错吗？

不一定。地址多写路径、少了 /v1、反向代理前缀丢失都会 404；模型名不存在也可能返回 404。先用 /v1/models 确认模型存在，再检查地址层级。

429 重试几次合适？

一般 2 到 3 次，使用递增等待并遵守 Retry-After。持续 429 说明并发或配额已经超限，继续重试只会加重拥堵，应降低批次大小或错峰执行。

工作流显示成功，但结果为空，怎么查？

打开执行记录逐节点看输出，确认模型返回是否被下游字段映射覆盖；检查输出是否被截断、是否触发内容过滤；再确认表达式引用的字段名与上一步实际结构一致。

自部署 n8n 还要注意什么网络问题？

确认容器或主机能解析并访问网关域名，检查代理环境变量、防火墙出站规则和 IP 白名单。定时触发和手动执行可能走不同实例，两个环境都要验证。

下一步

排查报错的通用原则是：先拿证据，再改配置；先修地址和凭证，再谈重试和超时。需要统一的 OpenAI 兼容入口、独立的虚拟 Key 和用量记录，可以先注册中商起航 AI 网关，模型与价格以模型价格为准。

相关阅读：