跳到主要内容

n8n 节点中的错误处理#

完善的错误处理对于构建健壮的 n8n 节点至关重要，它能在出现问题时为用户提供清晰反馈。n8n 提供两个专用错误类来处理节点实现中的不同类型故障：

NodeApiError#​

当处理外部 API 调用和 HTTP 请求时使用 NodeApiError。该错误类专门用于处理 API 响应错误，并提供增强功能来解析和呈现 API 相关故障，例如：

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

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

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

常见使用模式#​

对于基础API请求失败的情况，捕获错误并将其包装在 NodeApiError 中：

try {
	const response = await this.helpers.requestWithAuthentication.call(
		this,
		credentialType,
		options
	);
	return response;
} catch (error) {
	throw new NodeApiError(this.getNode(), error as JsonObject);
}

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

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：

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

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

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

常见使用模式#​

使用 NodeOperationError 进行用户输入验证：

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
	});
}

在处理多个项目时，应包含项目索引以提供更完善的错误上下文：

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,
		});
	}
}