服务器错误

GQLSTATUS 码分为类别和子类别。类码是一个 2 个字符的字符串，表示状态的一般条件，例如连接异常、数据异常等。子类码是一个 3 个字符的字符串，提供有关该条件的更详细信息。

下表列出了 GQLSTATUS 类别及其含义：

Neo4j-status 错误对象包含诊断信息，表示 Cypher 查询或命令执行的不成功结果，包括严重性、状态码、类别、描述、消息以及错误在查询文本中相关的位置。根据应用程序的不同，错误对象中的某些字段可能不可见。

错误对象包含以下字段：

更多信息请参见Neo4j 错误码列表。

服务器返回错误并不总是意味着这是致命错误。状态码也可能指示瞬时问题，这些问题在重试请求后可能会消失。服务器错误组决定了对事务的影响。

Neo4j 支持以 Java 异常形式表示的服务器错误。大多数异常实现了 HasStatus 接口，这意味着它们除了异常消息外，还有一个状态码。

在服务器端，异常包含普通的 Java 构造函数和方法，如 getMessage()、getCause() 等，此外还包含 HasStatus API 中的 status() 方法，该方法返回状态码。

异常还增加了新的强制字段 gqlStatus、statusDescription、diagnosticRecord，以及一个可选的 cause 字段。cause 字段本身也有自己的 GQLSTATUS、状态描述、诊断记录和消息。
保留了 getMessage() 方法，因为 Java 异常固有地具有此方法。并添加了一个新的分类字段，以涵盖客户端错误、瞬时错误和数据库错误的划分，这些划分目前是 Neo4j 码的一部分。所有这些字段构建了 GQLSTATUS 对象，该对象作为 Failure Bolt 消息的一部分发送给驱动程序。具体外观取决于驱动程序和服务器版本的组合。更多信息请参见服务器-驱动程序版本兼容性。

在驱动程序端，Neo4jException 扩展了与服务器端对应的方法。驱动程序接收 Failure Bolt 消息并提取状态码和错误消息。然后，它构建一个包含状态码、错误消息和其他相关信息的异常，并将其发送给客户端。

由于查询日志位于服务器端且作用于整个 DBMS，连接到同一 DBMS 的多个客户端会写入同一个查询日志。由于客户端可能使用不同的驱动程序版本，因此它们可能具有不同的错误框架格式。

在 Neo4j 5.25 中，查询日志的默认 JSON 模板已更新，包含一个 errorInfo 条目。此条目包含 GQLSTATUS、statusDescription、classification、position（如果适用）和 cause（如果适用），其内容与错误对象中的条目相同。

服务器和驱动程序通过 Bolt 协议相互通信。在握手过程中，它们会协商使用服务器和驱动程序都支持的最新 Bolt 协议版本。有关不同服务器版本支持的 Bolt 版本，请参阅Bolt 协议文档。

Neo4j 服务器版本 5.25 及更高版本在 JSON 格式的查询日志中提供了带有附加 GQL-status 错误对象的新错误框架。Bolt 协议自 5.7 版本起支持此功能，该版本对应于服务器端和驱动程序端的 5.26 或更高版本。

要充分利用新错误框架，您的服务器和驱动程序都必须支持它。版本低于 5.26 的驱动程序不会为异常发送任何 GQL-status 对象，即使服务器版本是 5.26 或更高。

如果版本 5.26 或更高版本的驱动程序与版本低于 5.26 的服务器通信，驱动程序需要使用 GQL-status 对象对异常进行填充。在这种情况下，所有异常都将返回默认的 GQLSTATUS 码 50N42。