附录E 错误代码

Halo 数据库服务器产生的所有消息都带有一个 5 字符错误码，遵循 SQL 标准的 "SQLSTATE" 约定。需要判断发生了何种错误的应用程序，通常应检测错误码，而不是查看文本错误消息——错误码在不同版本间更稳定，也不会因错误消息的本地化而改变。注意，Halo 产生的错误码中，一部分由 SQL 标准定义，另一部分是针对标准未定义的情形自行扩展或借鉴而来的。

按照标准，错误码的前两位表示一个错误类，后三位表示该类下的一个具体条件。因此，即使应用程序不认识某个具体错误码，也仍能从错误类推断出该如何处理。

表 E.1 列出了 Halo 1.0.16 定义的全部错误码（其中部分目前并未实际使用，而是由 SQL 标准所定义），同时列出了各个错误类。每个错误类都有一个后三位为 000 的"标准"错误码，该码仅用于落在该类内、但未分配更具体错误码的错误条件。

"条件名"一列所示的符号，是在 PL/pgSQL、PL/oraSQL 中使用的条件名。条件名既可大写也可小写。（注意：PL/pgSQL、PL/oraSQL 不识别警告类（区别于错误类）的条件名，即类 00、01、02。）

对于某些类型的错误，服务器会在消息中报告与该错误相关联的数据库对象名称（表、表列、数据类型或约束），例如导致 unique_violation 错误的唯一约束名。这些名称作为错误报告消息的独立字段提供，应用程序无需从可能已本地化的人类可读文本中去解析它们。

错误码在错误消息中的显示形如：

错误:  22012: 除以零

其中 22012 即为 SQLSTATE。

错误码速查（按错误类组织）

共收录 267 个错误码，按 SQL 标准错误类（Class）组织。标注 ¹ 者为 Halo 私有扩展错误码（见 E.2）。

Class 00 — Successful Completion

错误码	类型	条件名（Condition Name）
00000	成功	successful_completion

Class 01 — Warning

错误码	类型	条件名（Condition Name）
01000	警告	warning
01003	警告	null_value_eliminated_in_set_function
01004	警告	string_data_right_truncation
01006	警告	privilege_not_revoked
01007	警告	privilege_not_granted
01008	警告	implicit_zero_bit_padding
0100C	警告	dynamic_result_sets_returned
01P01	警告	deprecated_feature

Class 02 — No Data (this is also a warning class per the SQL standard)

错误码	类型	条件名（Condition Name）
02000	警告	no_data
02001	警告	no_additional_dynamic_result_sets_returned

Class 03 — SQL Statement Not Yet Complete

错误码	类型	条件名（Condition Name）
03000	错误	sql_statement_not_yet_complete

Class 08 — Connection Exception

错误码	类型	条件名（Condition Name）
08000	错误	connection_exception
08001	错误	sqlclient_unable_to_establish_sqlconnection
08003	错误	connection_does_not_exist
08004	错误	sqlserver_rejected_establishment_of_sqlconnection
08006	错误	connection_failure
08007	错误	transaction_resolution_unknown
08P01	错误	protocol_violation

Class 09 — Triggered Action Exception

错误码	类型	条件名（Condition Name）
09000	错误	triggered_action_exception

Class 0A — Feature Not Supported

错误码	类型	条件名（Condition Name）
0A000	错误	feature_not_supported

Class 0B — Invalid Transaction Initiation

错误码	类型	条件名（Condition Name）
0B000	错误	invalid_transaction_initiation

Class 0F — Locator Exception

错误码	类型	条件名（Condition Name）
0F000	错误	locator_exception
0F001	错误	invalid_locator_specification

Class 0L — Invalid Grantor

错误码	类型	条件名（Condition Name）
0L000	错误	invalid_grantor
0LP01	错误	invalid_grant_operation

Class 0P — Invalid Role Specification

错误码	类型	条件名（Condition Name）
0P000	错误	invalid_role_specification

Class 0Z — Diagnostics Exception

错误码	类型	条件名（Condition Name）
0Z000	错误	diagnostics_exception
0Z002	错误	stacked_diagnostics_accessed_without_active_handler

Class 20 — Case Not Found

错误码	类型	条件名（Condition Name）
20000	错误	case_not_found

Class 21 — Cardinality Violation

错误码	类型	条件名（Condition Name）
21000	错误	cardinality_violation

Class 22 — Data Exception

错误码	类型	条件名（Condition Name）
22000	错误	data_exception
22001	错误	string_data_right_truncation
22002	错误	null_value_no_indicator_parameter
22003	错误	numeric_value_out_of_range
22004	错误	null_value_not_allowed
22005	错误	error_in_assignment
22007	错误	invalid_datetime_format
22008	错误	datetime_field_overflow
22008	错误	datetime_value_out_of_range
22009	错误	invalid_time_zone_displacement_value
2200B	错误	escape_character_conflict
2200C	错误	invalid_use_of_escape_character
2200D	错误	invalid_escape_octet
2200F	错误	zero_length_character_string
2200G	错误	most_specific_type_mismatch
2200H	错误	sequence_generator_limit_exceeded
2200L	错误	not_an_xml_document
2200M	错误	invalid_xml_document
2200N	错误	invalid_xml_content
2200S	错误	invalid_xml_comment
2200T	错误	invalid_xml_processing_instruction
22010	错误	invalid_indicator_parameter_value
22011	错误	substring_error
22012	错误	division_by_zero
22013	错误	invalid_preceding_or_following_size
22014	错误	invalid_argument_for_ntile_function
22015	错误	interval_field_overflow
22016	错误	invalid_argument_for_nth_value_function
22018	错误	invalid_character_value_for_cast
22019	错误	invalid_escape_character
2201B	错误	invalid_regular_expression
2201E	错误	invalid_argument_for_logarithm
2201F	错误	invalid_argument_for_power_function
2201G	错误	invalid_argument_for_width_bucket_function
2201W	错误	invalid_row_count_in_limit_clause
2201X	错误	invalid_row_count_in_result_offset_clause
22021	错误	character_not_in_repertoire
22022	错误	indicator_overflow
22023	错误	invalid_parameter_value
22024	错误	unterminated_c_string
22025	错误	invalid_escape_sequence
22026	错误	string_data_length_mismatch
22027	错误	trim_error
2202E	错误	array_element_error
2202E	错误	array_subscript_error
2202G	错误	invalid_tablesample_repeat
2202H	错误	invalid_tablesample_argument
22030	错误	duplicate_json_object_key_value
22031	错误	invalid_argument_for_sql_json_datetime_function
22032	错误	invalid_json_text
22033	错误	invalid_sql_json_subscript
22034	错误	more_than_one_sql_json_item
22035	错误	no_sql_json_item
22036	错误	non_numeric_sql_json_item
22037	错误	non_unique_keys_in_a_json_object
22038	错误	singleton_sql_json_item_required
22039	错误	sql_json_array_not_found
2203A	错误	sql_json_member_not_found
2203B	错误	sql_json_number_not_found
2203C	错误	sql_json_object_not_found
2203D	错误	too_many_json_array_elements
2203E	错误	too_many_json_object_members
2203F	错误	sql_json_scalar_required
2203G	错误	sql_json_item_cannot_be_cast_to_target_type
22P01	错误	floating_point_exception
22P02	错误	invalid_text_representation
22P03	错误	invalid_binary_representation
22P04	错误	bad_copy_file_format
22P05	错误	untranslatable_character
22P06	错误	nonstandard_use_of_escape_character
UEFFF ¹	错误	ora_exception_error

Class 23 — Integrity Constraint Violation

错误码	类型	条件名（Condition Name）
23000	错误	integrity_constraint_violation
23001	错误	restrict_violation
23502	错误	not_null_violation
23503	错误	foreign_key_violation
23505	错误	unique_violation
23514	错误	check_violation
23P01	错误	exclusion_violation

Class 24 — Invalid Cursor State

错误码	类型	条件名（Condition Name）
24000	错误	invalid_cursor_state

Class 25 — Invalid Transaction State

错误码	类型	条件名（Condition Name）
25000	错误	invalid_transaction_state
25001	错误	active_sql_transaction
25002	错误	branch_transaction_already_active
25003	错误	inappropriate_access_mode_for_branch_transaction
25004	错误	inappropriate_isolation_level_for_branch_transaction
25005	错误	no_active_sql_transaction_for_branch_transaction
25006	错误	read_only_sql_transaction
25007	错误	schema_and_data_statement_mixing_not_supported
25008	错误	held_cursor_requires_same_isolation_level
25P01	错误	no_active_sql_transaction
25P02	错误	in_failed_sql_transaction
25P03	错误	idle_in_transaction_session_timeout

Class 26 — Invalid SQL Statement Name

错误码	类型	条件名（Condition Name）
26000	错误	invalid_sql_statement_name

Class 27 — Triggered Data Change Violation

错误码	类型	条件名（Condition Name）
27000	错误	triggered_data_change_violation

Class 28 — Invalid Authorization Specification

错误码	类型	条件名（Condition Name）
28000	错误	invalid_authorization_specification
28P01	错误	invalid_password

Class 2B — Dependent Privilege Descriptors Still Exist

错误码	类型	条件名（Condition Name）
2B000	错误	dependent_privilege_descriptors_still_exist
2BP01	错误	dependent_objects_still_exist

Class 2D — Invalid Transaction Termination

错误码	类型	条件名（Condition Name）
2D000	错误	invalid_transaction_termination

Class 2F — SQL Routine Exception

错误码	类型	条件名（Condition Name）
2F000	错误	sql_routine_exception
2F002	错误	modifying_sql_data_not_permitted
2F003	错误	prohibited_sql_statement_attempted
2F004	错误	reading_sql_data_not_permitted
2F005	错误	function_executed_no_return_statement

Class 34 — Invalid Cursor Name

错误码	类型	条件名（Condition Name）
34000	错误	invalid_cursor_name

Class 38 — External Routine Exception

错误码	类型	条件名（Condition Name）
38000	错误	external_routine_exception
38001	错误	containing_sql_not_permitted
38002	错误	modifying_sql_data_not_permitted
38003	错误	prohibited_sql_statement_attempted
38004	错误	reading_sql_data_not_permitted

Class 39 — External Routine Invocation Exception

错误码	类型	条件名（Condition Name）
39000	错误	external_routine_invocation_exception
39001	错误	invalid_sqlstate_returned
39004	错误	null_value_not_allowed
39P01	错误	trigger_protocol_violated
39P02	错误	srf_protocol_violated
39P03	错误	event_trigger_protocol_violated

Class 3B — Savepoint Exception

错误码	类型	条件名（Condition Name）
3B000	错误	savepoint_exception
3B001	错误	invalid_savepoint_specification

Class 3D — Invalid Catalog Name

错误码	类型	条件名（Condition Name）
3D000	错误	invalid_catalog_name

Class 3F — Invalid Schema Name

错误码	类型	条件名（Condition Name）
3F000	错误	invalid_schema_name

Class 40 — Transaction Rollback

错误码	类型	条件名（Condition Name）
40000	错误	transaction_rollback
40001	错误	serialization_failure
40002	错误	transaction_integrity_constraint_violation
40003	错误	statement_completion_unknown
40P01	错误	deadlock_detected

Class 42 — Syntax Error or Access Rule Violation

错误码	类型	条件名（Condition Name）
26000	错误	undefined_pstatement
34000	错误	undefined_cursor
3D000	错误	undefined_database
3F000	错误	undefined_schema
42000	错误	syntax_error_or_access_rule_violation
42501	错误	insufficient_privilege
42601	错误	syntax_error
42602	错误	invalid_name
42611	错误	invalid_column_definition
42622	错误	name_too_long
42701	错误	duplicate_column
42702	错误	ambiguous_column
42703	错误	undefined_column
42704	错误	undefined_object
42710	错误	duplicate_object
42712	错误	duplicate_alias
42723	错误	duplicate_function
42725	错误	ambiguous_function
42803	错误	grouping_error
42804	错误	datatype_mismatch
42809	错误	wrong_object_type
42830	错误	invalid_foreign_key
42846	错误	cannot_coerce
42883	错误	undefined_function
428C9	错误	generated_always
42939	错误	reserved_name
42P01	错误	undefined_table
42P02	错误	undefined_parameter
42P03	错误	duplicate_cursor
42P04	错误	duplicate_database
42P05	错误	duplicate_prepared_statement
42P06	错误	duplicate_schema
42P07	错误	duplicate_table
42P08	错误	ambiguous_parameter
42P09	错误	ambiguous_alias
42P10	错误	invalid_column_reference
42P11	错误	invalid_cursor_definition
42P12	错误	invalid_database_definition
42P13	错误	invalid_function_definition
42P14	错误	invalid_prepared_statement_definition
42P15	错误	invalid_schema_definition
42P16	错误	invalid_table_definition
42P17	错误	invalid_object_definition
42P18	错误	indeterminate_datatype
42P19	错误	invalid_recursion
42P20	错误	windowing_error
42P21	错误	collation_mismatch
42P22	错误	indeterminate_collation

Class 44 — WITH CHECK OPTION Violation

错误码	类型	条件名（Condition Name）
44000	错误	with_check_option_violation

Class 53 — Insufficient Resources

错误码	类型	条件名（Condition Name）
53000	错误	insufficient_resources
53100	错误	disk_full
53200	错误	out_of_memory
53300	错误	too_many_connections
53400	错误	configuration_limit_exceeded

Class 54 — Program Limit Exceeded

错误码	类型	条件名（Condition Name）
54000	错误	program_limit_exceeded
54001	错误	statement_too_complex
54011	错误	too_many_columns
54023	错误	too_many_arguments

Class 55 — Object Not In Prerequisite State

错误码	类型	条件名（Condition Name）
55000	错误	object_not_in_prerequisite_state
55006	错误	object_in_use
55P02	错误	cant_change_runtime_param
55P03	错误	lock_not_available
55P04	错误	unsafe_new_enum_value_usage

Class 57 — Operator Intervention

错误码	类型	条件名（Condition Name）
57000	错误	operator_intervention
57014	错误	query_canceled
57P01	错误	admin_shutdown
57P02	错误	crash_shutdown
57P03	错误	cannot_connect_now
57P04	错误	database_dropped
57P05	错误	idle_session_timeout

Class 58 — System Error (errors external to Halo itself)

错误码	类型	条件名（Condition Name）
58000	错误	system_error
58030	错误	io_error
58P01	错误	undefined_file
58P02	错误	duplicate_file

Class 72 — Snapshot Failure

错误码	类型	条件名（Condition Name）
72000	错误	snapshot_too_old

Class F0 — Configuration File Error

错误码	类型	条件名（Condition Name）
F0000	错误	config_file_error
F0001	错误	lock_file_exists

Class HV — Foreign Data Wrapper Error (SQL/MED)

错误码	类型	条件名（Condition Name）
HV000	错误	fdw_error
HV001	错误	fdw_out_of_memory
HV002	错误	fdw_dynamic_parameter_value_needed
HV004	错误	fdw_invalid_data_type
HV005	错误	fdw_column_name_not_found
HV006	错误	fdw_invalid_data_type_descriptors
HV007	错误	fdw_invalid_column_name
HV008	错误	fdw_invalid_column_number
HV009	错误	fdw_invalid_use_of_null_pointer
HV00A	错误	fdw_invalid_string_format
HV00B	错误	fdw_invalid_handle
HV00C	错误	fdw_invalid_option_index
HV00D	错误	fdw_invalid_option_name
HV00J	错误	fdw_option_name_not_found
HV00K	错误	fdw_reply_handle
HV00L	错误	fdw_unable_to_create_execution
HV00M	错误	fdw_unable_to_create_reply
HV00N	错误	fdw_unable_to_establish_connection
HV00P	错误	fdw_no_schemas
HV00Q	错误	fdw_schema_not_found
HV00R	错误	fdw_table_not_found
HV010	错误	fdw_function_sequence_error
HV014	错误	fdw_too_many_handles
HV021	错误	fdw_inconsistent_descriptor_information
HV024	错误	fdw_invalid_attribute_value
HV090	错误	fdw_invalid_string_length_or_buffer_length
HV091	错误	fdw_invalid_descriptor_field_identifier

Class P0 — PL/pgSQL Error

错误码	类型	条件名（Condition Name）
P0000	错误	plpgsql_error
P0001	错误	raise_exception
P0002	错误	no_data_found
P0003	错误	too_many_rows
P0004	错误	assert_failure

Class XX — Internal Error

错误码	类型	条件名（Condition Name）
XX000	错误	internal_error
XX001	错误	data_corrupted
XX002	错误	index_corrupted

Halo 私有扩展错误码

除 SQL 标准定义的错误码外，Halo 针对 Oracle 兼容模式新增了以下私有错误码，类码 UE 为 Halo 扩展类，不属于 SQL 标准：

错误码	类型	条件名	说明
UEFFF ¹	错误	ora_exception_error	Oracle 兼容模式下，PL/oraSQL 中抛出的未映射异常（undefined exception）。

触发示例（Oracle 兼容模式，端口 1521）

在 PL/oraSQL 块中使用 RAISE 抛出该条件名：

halo0root@oracle=# DO $$
BEGIN
  RAISE ora_exception_error USING MESSAGE = 'test undefined halo exception';
END $$;
错误:  UEFFF: test undefined halo exception
背景:  在RAISE的第3行的PL/oraSQL函数inline_code_block
位置:  exec_stmt_raise, plora_exec.c:5457

Oracle 风格的 RAISE_APPLICATION_ERROR(-20001, msg) 走的是 Halo 另一套错误码体系（如 HERR-20001），与 SQLSTATE 的 UEFFF 不同。捕获 Oracle 兼容模式的自定义异常时，应注意区分这两种抛出方式。

MySQL 协议端口的错误码差异

Halo 通过 MySQL 协议端口（默认 3306）对外提供 MySQL 兼容访问。该端口返回的是 MySQL 原生格式的错误码，而非 SQLSTATE 五位码，这是 MySQL 客户端协议的固有行为。

MySQL 错误码格式

MySQL 错误信息形如：

ERROR 1478 (HY000) at line 1: 语法错误 在 "SELCT" 或附近的

其中：

• 1478：MySQL 数字错误码（4 位数字）。
• HY000：MySQL 的 SQLSTATE（HY000 表示通用错误，与 SQL 标准的 SQLSTATE 体系不同）。

对照示例

同一"语法错误"场景，原生端口与 MySQL 协议端口返回的错误码格式不同：

端口	错误码格式	示例
原生端口（1921）/ Oracle 兼容端口（1521）	SQLSTATE 五位码	42601: syntax error...
MySQL 协议端口（3306）	MySQL 数字码 + HY000	ERROR 1478 (HY000)

开发建议：通过 MySQL 客户端/驱动（端口 3306）连接 Halo 时，按 MySQL 数字错误码（如 1064 语法错误、1146 表不存在、1050 表已存在）进行错误捕获；通过原生端口或 Oracle 兼容端口连接时，按本附录的 SQLSTATE 进行捕获。两套错误码体系不互通。

关于条件名

"条件名"一列中，少量错误码（如 22008、34000、3D000、26000、3F000）仅有 SQLSTATE 而无标准条件名，本附录以宏名（errcode macro）的小写形式列出，仅供识别；此类名称不可用于 RAISE 或 EXCEPTION WHEN。其余条件名可用于 PL/pgSQL、PL/oraSQL 中的异常捕获，例如：

EXCEPTION
  WHEN division_by_zero THEN ...