Error Codes Reference

AngaraBase uses an internal EngineErrorKind enum as the single source of truth for error codes. At the protocol boundary, engine errors are translated to PostgreSQL SQLSTATE codes via the ERROR_REGISTRY.

Error Categories

Category	Description
`InvalidInput`	Client passed invalid parameters or malformed query
`TransactionControl`	Transaction state errors (serialization failures, conflicts)
`AccessControl`	Insufficient privileges
`ResourceLimit`	Resource exhaustion (memory, connections, locks)
`InternalError`	Internal engine errors (bugs, invariant violations)
`IoError`	Disk/network I/O errors

Error Code Registry

EngineErrorKind	PG SQLSTATE	PG Code Name	Category	Description
`InvalidParameter`	`22023`	`invalid_parameter_value`	`InvalidInput`	Caller passed an invalid parameter (validation failure inside the engine).
`TransactionAborted`	`40001`	`serialization_failure`	`TransactionControl`	Transaction aborted by the engine (serialization failure, conflict, …).
`LockTimeout`	`55P03`	`lock_not_available`	`ResourceLimit`	Lock acquisition exceeded the configured timeout.
`AccessDenied`	`42501`	`insufficient_privilege`	`AccessControl`	Authorization / RBAC denial inside the engine.
`InternalError`	`XX000`	`internal_error`	`InternalError`	Catch-all internal error (unexpected state, broken invariant).
`DuplicateKey`	`23505`	`unique_violation`	`InvalidInput`	Unique-key violation (catalogued for clean SQLSTATE mapping).
`ConstraintViolation`	`23000`	`integrity_constraint_violation`	`InvalidInput`	Generic constraint violation (FK, CHECK, NOT NULL, …).
`NotFound`	`42704`	`undefined_object`	`InvalidInput`	Object does not exist (table, schema, row, …).
`IoError`	`58030`	`io_error`	`IoError`	I/O error from storage / WAL / recovery layer.
`ResourceExhausted`	`53000`	`insufficient_resources`	`ResourceLimit`	Resource exhaustion (memory limits, connection limits, …).
`QosQueueFull`	`53600`	`qos_queue_full`	`ResourceLimit`	QoS queue full — per-level cap on concurrent/queued requests exceeded.
`FeatureNotSupported`	`0A000`	`feature_not_supported`	`InvalidInput`	Requested feature is not supported by this version of AngaraBase.
`UndefinedFunction`	`42883`	`undefined_function`	`InvalidInput`	Operator or function not found for the given argument types.
`InvalidColumnReference`	`42P10`	`invalid_column_reference`	`InvalidInput`	Invalid column reference (e.g., ORDER BY ordinal out of range).
`SyntaxError`	`42601`	`syntax_error`	`InvalidInput`	SQL syntax error in the submitted query.
`NoActiveSqlTransaction`	`25P01`	`no_active_sql_transaction`	`TransactionControl`	Command requires an active transaction but none is in progress.
`ActiveSqlTransaction`	`25001`	`active_sql_transaction`	`TransactionControl`	Command cannot be executed within an active transaction block.
`ReadOnlySqlTransaction`	`25006`	`read_only_sql_transaction`	`TransactionControl`	Write operation attempted in a read-only transaction.
`IdleInTransactionTimeout`	`57P01`	`idle_in_transaction_session_timeout`	`ResourceLimit`	Session exceeded idle_in_transaction_session_timeout.

Troubleshooting

Handling `TransactionAborted` (40001)

When AngaraBase returns SQLSTATE 40001 (serialization_failure), the client should retry the transaction. This is standard MVCC behaviour — a concurrent writer committed first.

-- Client retry pattern:
BEGIN;
-- ... operations ...
-- If you get 40001, retry from BEGIN
COMMIT;

Handling `ResourceExhausted` (53000)

Hard resource exhaustion (memory / connection limits). Check angarabase_server_connections_active; if near max_connections, either:

Increase max_connections (requires restart — it is an instance-scope setting)
Use connection pooling (PgBouncer)

Handling `QosQueueFull` (53600)

The per-ServiceLevel QoS admission cap was exceeded. Unlike 53000, this code is transient and safe to retry: back off with jitter and let lower-priority work drain. See the Resource Contracts reference for the full fail-closed boundary table.

Keyboard shortcuts

AngaraBook