Errors & SQLSTATEs

Connection and transient

Transactions

Data

None of these is retryable.

Integrity

Fix the data, not the retry loop. ORMs map these to their IntegrityError class.

Schema and SQL

Feature not supported

0A000 is reserved for features the engine recognises and has deliberately not implemented; the message always says what to do instead. Every other refused shape comes back as 42601 or 42703 with the alternative named in the message (see above). The 0A000 cases:

• triggers are not supported yet: a synchronous plpgsql-subset trigger engine … is on the roadmap. Today, react to writes with an ingest rule → pipeline, or an Action; validation belongs in CHECK constraints. since 0.1.43
• cannot use subquery in check constraint, and a CHECK with arithmetic or function calls — the message lists the supported predicate forms.
• A FOREIGN KEY declared DEFERRABLE, INITIALLY DEFERRED, or with ON DELETE / ON UPDATE CASCADE / SET NULL / SET DEFAULT. The engine enforces only what its write gate can keep, so these options are refused at DDL rather than accepted and ignored. Drop the option; cascade in the application.

The full current list is on Limits & differences.

Authentication

Building a retry loop

RETRY_TXN   = {"40001"}            # re-run the whole transaction
RETRY_CONN  = {"08006"}            # reconnect first
RETRY_ONCE  = {"XX000"}
 
def should_retry(sqlstate, attempt):
    if sqlstate in RETRY_TXN or sqlstate in RETRY_CONN:
        return attempt < 8
    if sqlstate in RETRY_ONCE:
        return attempt < 1
    return False                   # 22xxx, 23xxx, 42xxx, 0A000, 28xxx: never

Two rules make the loop safe. First, retry the transaction, not the statement: a 40001 means the values you computed are stale. Second, make the transaction idempotent before you retry a connection failure, because the previous attempt may have committed; the transfer pattern shows the journal-row technique.

NOTICEs you will see

A NOTICE is not an error. It arrives on the same connection and most drivers hand it to a callback rather than raising.

VARCHAR(n) and TIMESTAMP(p) no longer raise a precision notice: both are honoured since 0.1.43.

Reading them:

# psycopg 3
conn.add_notice_handler(lambda d: print(d.severity, d.message_primary))

// node-postgres
client.on('notice', (msg) => console.warn(msg.message))

A strong read that would be incomplete

Under a sustained write burst a read can be refused rather than served partially:

strong read aborted: the WAL overlay truncated at N entries, so the result
would be incomplete — compaction is catching up; retry shortly

On the Postgres wire this arrives as XX000 with that message; on gRPC it is FAILED_PRECONDITION. The engine never returns a partial answer in its place. Compaction is already scheduled when this fires, so a retry after a short pause converges. If you see it often, run dodil data table compact after your bulk loads; see Performance & layout.