在 n8n 中为 webhook/定时/无人值守工作流配置错…

当构建 webhook 触发的 API 工作流或定时/生产环境无人值守工作流时，用结构化错误输出、状态码映射和重试机制让失败可见、可恢复。

适用场景

解决思路

1. 对任何 API 形态的工作流（webhook 触发器 + Respond to Webhook），把每个可能出错节点的错误输出都接上，并让成功与错误两条路径都终止于 Respond to Webhook，避免错误分支悬空导致调用方超时。
2. 把状态码映射到失败原因：调用方的错用 4xx，自己的错用 5xx；错误路径不要默认返回 200，否则调用方以为成功、处理空数据，形成静默失败。
3. 对任何无人值守工作流（定时、cron、队列驱动、agent 工具），设置工作流级错误工作流，捕获节点级处理漏掉的超时、节点间崩溃、未接线节点的错误；通过 update_workflow 的 setWorkflowSettings.errorWorkflow 设置（n8n 2.29.0+），目标必须是已发布且含激活 Error Trigger 的工作流，否则更新被拒。
4. 错误响应体要结构化，不要只返回 "Internal Server Error"，使用 { "error": "<短标识>", "message": "<人类可读>" } 形式。
5. 对发起网络调用的节点配置 retryOnFail，让瞬时 429 和上游抖动在到达错误路径前被吸收。
6. 内部一次性工作流（只有你自己用、每次运行都盯着、失败成本只是重跑）可以放宽，保持默认 onError: 'stopWorkflow'；一旦输出会被他人（下游系统、终端用户、值班人员）看到，就必须遵守上述硬性要求。
7. API 工作流的标准形态：Webhook 触发器分两条路径——成功路径经处理到 Respond to Webhook（200 + body），任意节点的错误输出到 Respond to Webhook（5xx + 结构化错误体），可选再记录到错误追踪/日志/通知渠道。
8. 对做输入校验的 webhook API，采用 Set IIFE 模式而非逐字段写 IF/Switch 链：把 usage 示例结构（Webhook → Set(Validate Schema) → If Params Valid → 业务逻辑 → 成功/400 Respond）搬进端点，替换 NoOp 占位为真实逻辑。
9. 编辑 IIFE 以适配你的 schema：更新 REQUIRED_SCHEMA 和 Set 节点表达式中的逐字段检查，模式是机械的——存在性检查、类型检查、约束检查、push 到 errors[]。
10. 不要改动输出形状：valid、validationError、details、requiredSchema 是 Respond 节点消费的契约，重命名会破坏响应体。
11. 每个可能出错的节点需要两处改动：设置 onError: 'continueErrorOutput'，并把 output(1) 接到错误处理器；两者缺一不可，否则就是静默失败模式。
12. 在接错误路径之前，先对任何发起网络调用的节点（HTTP Request、Gmail/Slack/Discord 等通信、DB、AI、第三方 API 节点）配置节点级重试：{ retryOnFail: true, maxTries: 3, waitBetweenTries: 5000 }；引擎对任何错误都重试、无按状态码过滤，maxTries 上限 5、waitBetweenTries 上限 5000ms。
13. 按原因映射状态码：必填字段缺失或类型错误→400 validation_error（用 Set 校验器或简单 IF/Switch + 专用 400 Respond 提前检查，不走错误输出，最好回显 schema 让调用方自纠）；认证缺失或无效→401 unauthorized；已认证但无权→403 forbidden；请求中的资源 ID 不存在→404 not_found（从查找结果分支，而非查找错误）；操作与当前状态冲突（重复、竞态）→409 conflict（用逻辑检测，不用错误输出）；调用方超限→429 rate_limit_exceeded（设置 Retry-After 头）；节点抛出且原因不明→500 internal_error（错误输出路径）；第三方 API 出错→502 upstream_error（HTTP Request 节点的错误输出）；工作流当前无法处理（下游宕机、上游限流）→503 service_unavailable（按具体错误检测并返回提示）；第三方 API 超时→504 upstream_timeout（按错误消息过滤错误输出）。
14. 区分两条流程：校验失败（4xx）在工作之前通过 IF/Switch 分支检查，每种形状用专用 Respond（400 缺字段、401 无认证等）；执行失败（5xx）来自错误输出（“我们试了，但坏了”），所有 5xx 可共用一个错误响应器，必要时通过检查失败节点区分 body 中的 error 码。
15. 当错误路径只在状态码和消息文本上不同（body 形状相同、无 header/content-type 变化）时，不要用 Switch 扇出到 N 个 Respond 节点；Respond to Webhook 节点接受 Response Code 和 body 字段的表达式，可内联计算状态码，用一个 Respond 节点承载整条错误路径。
16. 只有当响应在结构上不同（不同 header、不同 body 形状、重定向、不同 content-type）时，Switch + N 个 Respond 才值得使用。
17. 对无人值守工作流配置实例级错误工作流（或按工作流覆盖），指向一个工作流：捕获失败（工作流名、执行 ID、错误、堆栈）、通知某人（Slack、邮件、值班）、可选入队重试（带退避）。

适用边界 · 注意事项

• 内部一次性工作流，只有你自己使用、每次运行都盯着、失败成本只是“我注意到并重跑”时，可保持默认 onError: 'stopWorkflow'。
• 当错误响应在结构上相同、仅状态码或消息文本不同时，不要用 Switch 扇出到多个 Respond 节点。
• 不要用 Code 节点捕获错误并作为数据返回，这会让下游看到错误形状的数据并继续执行；应让它抛出并配置 onError: 'continueErrorOutput' 接错误路径。