Skip to content

n8n 节点中的错误处理(Error handling in n8n nodes)#

适当的错误处理对于创建稳健的 n8n 节点至关重要，它可以在出现问题时向用户提供清晰的反馈。n8n 提供了两种专门的错误类，用于处理节点实现中的不同类型的故障：

🌐 Proper error handling is crucial for creating robust n8n nodes that provide clear feedback to users when things go wrong. n8n provides two specialized error classes to handle different types of failures in node implementations:

NodeApiError#

在处理外部 API 调用和 HTTP 请求时使用 NodeApiError。该错误类专门用于处理 API 响应错误，并提供用于解析和展示与 API 相关失败的增强功能，例如：

🌐 Use NodeApiError when dealing with external API calls and HTTP requests. This error class is specifically designed to handle API response errors and provides enhanced features for parsing and presenting API-related failures such as:

  • HTTP 请求失败
  • 外部 API 错误
  • 身份验证/授权失败
  • 速率限制错误
  • 服务不可用错误

使用以下模式初始化新的 NodeApiError 实例：

🌐 Initialize new NodeApiError instances using the following pattern:

1
new NodeApiError(node: INode, errorResponse: JsonObject, options?: NodeApiErrorOptions)

常见使用模式(Common usage patterns)#

对于基本的 API 请求失败，捕获错误并将其封装在 NodeApiError 中：

🌐 For basic API request failures, catch the error and wrap it in NodeApiError:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
try {
	const response = await this.helpers.requestWithAuthentication.call(
		this,
		credentialType,
		options
	);
	return response;
} catch (error) {
	throw new NodeApiError(this.getNode(), error as JsonObject);
}

使用自定义消息处理特定的 HTTP 状态码：

🌐 Handle specific HTTP status codes with custom messages:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
try {
	const response = await this.helpers.requestWithAuthentication.call(
		this,
		credentialType,
		options
	);
	return response;
} catch (error) {
	if (error.httpCode === "404") {
		const resource = this.getNodeParameter("resource", 0) as string;
		const errorOptions = {
			message: `${
				resource.charAt(0).toUpperCase() + resource.slice(1)
			} not found`,
			description:
				"The requested resource could not be found. Please check your input parameters.",
		};
		throw new NodeApiError(
			this.getNode(),
			error as JsonObject,
			errorOptions
		);
	}

	if (error.httpCode === "401") {
		throw new NodeApiError(this.getNode(), error as JsonObject, {
			message: "Authentication failed",
			description: "Please check your credentials and try again.",
		});
	}

	throw new NodeApiError(this.getNode(), error as JsonObject);
}

NodeOperationError#

使用 NodeOperationError 来:

🌐 Use NodeOperationError for:

  • 操作错误
  • 验证失败
  • 与外部 API 调用无关的配置问题
  • 输入验证错误
  • 缺少必需参数
  • 数据转换错误
  • 工作流逻辑错误

使用以下模式初始化新的 NodeOperationError 实例：

1
new NodeOperationError(node: INode, error: Error | string | JsonObject, options?: NodeOperationErrorOptions)

常见使用模式(Common usage patterns)#

使用 NodeOperationError 来验证用户输入：

🌐 Use NodeOperationError for validating user inputs:

1
2
3
4
5
6
7
8
9
const email = this.getNodeParameter("email", itemIndex) as string;

if (email.indexOf("@") === -1) {
	const description = `The email address '${email}' in the 'email' field isn't valid`;
	throw new NodeOperationError(this.getNode(), "Invalid email address", {
		description,
		itemIndex, // for multiple items, this will link the error to the specific item
	});
}

处理多个项目时，请包含项目索引以便更好地了解错误上下文：

🌐 When processing multiple items, include the item index for better error context:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
for (let i = 0; i < items.length; i++) {
	try {
		// Process item
		const result = await processItem(items[i]);
		returnData.push(result);
	} catch (error) {
		if (this.continueOnFail()) {
			returnData.push({
				json: { error: error.message },
				pairedItem: { item: i },
			});
			continue;
		}

		throw new NodeOperationError(this.getNode(), error as Error, {
			description: error.description,
			itemIndex: i,
		});
	}
}