Error Reference

AionDB maps database errors to PostgreSQL-style SQLSTATE codes where possible. Clients can inspect SQLSTATE instead of parsing message text.

SQLSTATE codes

The full set of SQLSTATEs the engine emits today. Codes are grouped by class.

Class 0A — feature not supported

Class 20 / 22 — data exceptions

Class 23 — integrity constraint violation

Class 24 / 34 — cursor

Class 25 / 2B — transaction state

Class 28 — authentication

Class 3B / 3D / 3F — catalog & savepoints

Class 40 — transaction rollback

Class 42 — syntax & access rule

Class 53 / 54 — resource & program limit

Class 55 — object not in prerequisite state

Class 57 — operator intervention

Class P0 — PL/pgSQL

Class XX — internal

Error handling guidance

Applications should branch on SQLSTATE class or exact SQLSTATE where possible:

• 23xxx for constraint violations;
• 25xxx for transaction-state issues;
• 28xxx for authentication issues;
• 40xxx for retryable transaction conflicts;
• 42xxx for syntax or object lookup problems;
• 57xxx for cancellation and shutdown cases.

Message text is for humans. SQLSTATE is for programs. Error wording may become clearer over time, but applications should not depend on exact message strings.

Examples

Undefined table:

SELECT * FROM missing_table;

Expected class: 42xxx, with 42P01 when mapped precisely.

Unsupported feature:

CREATE EXTENSION pg_trgm;

Expected class: 0A000 when the feature is intentionally unsupported.

Constraint violation:

CREATE TABLE unique_demo (id INT PRIMARY KEY);
INSERT INTO unique_demo VALUES (1);
INSERT INTO unique_demo VALUES (1);

Expected class: 23xxx, with 23505 for unique violation where implemented.

Transaction errors

Errors inside a transaction can affect subsequent statements. Drivers often expect PostgreSQL-style transaction state handling, so test the exact client behavior:

BEGIN;
SELECT * FROM missing_table;
ROLLBACK;

Record whether the client can continue after rollback and which SQLSTATE was returned for the original error.

Reporting errors

When reporting an error, include:

• SQL text;
• SQLSTATE;
• message;
• whether it happened over pgwire or embedded API;
• transaction state;
• AionDB commit hash.

If another database is the reference, include its SQLSTATE and message too. That makes compatibility work precise.