Error Codes

Note: This file is hand-maintained. When the error hierarchy in lib/errors.ts or the protocol code map in protocol/binary-server.ts changes, update this document to match. Ports the request in geldata/gel#6648.

Disc surfaces errors in three layers:

1. Disc error classes — TypeScript subclasses of DiscError raised by the parser, compiler, runtime, and protocol layers. These are what your code catches when calling Disc as a library.
2. HTTP error envelopes — what POST /query and POST /transaction/* return, with a string extensions.code and, for failures inside PostgreSQL, the SQLSTATE. The TypeScript SDK turns these into its own error classes.
3. Gel wire protocol error codes — 32-bit numeric codes returned to clients over the binary protocol. Disc maps each error class to one of these codes for compatibility with the existing Gel client SDKs.

When you receive an error from a Disc client SDK, the code field is a protocol code (column 2 below); the name field corresponds to a Disc error class (column 1).

Table of Contents

• HTTP Error Envelopes
• Disc Error Classes
• Gel Protocol Error Codes
• Class → Protocol Code Mapping

HTTP Error Envelopes

A failed POST /query answers { "errors": [{ "message", "extensions": { "code", … } }] }. The HTTP status is 400 for every query error except an access policy violation or a refused persistent configure (403), 408 for a timeout and 500 for an internal error; 413 (body too large), 401/403, 404 and 429 come from the HTTP layer with a plain { "error": "…" } body.

SQLSTATEs worth matching on: 23505 unique violation (a duplicate on an exclusive constraint or unique index; constraint names it), 23503 foreign-key violation, 23514 check violation (a regexp, one_of, min_value… constraint on a property or scalar type, or an expression on constraint), 21000 cardinality violation (assert_single found several, or an object cast <T><uuid>$p named an id no T has: 'default::T' with id '…' does not exist), 40001 serialization failure and 40P01 deadlock (retry the whole transaction). The SDK maps these to UniqueViolationError, ForeignKeyViolationError, ConstraintViolationError, CardinalityViolationError, SerializationFailureError and DeadlockError, all instanceof DiscQueryError with .sqlState.

A value PostgreSQL can’t take fails with PostgreSQL’s message worded with Gel’s type names, as Gel words it: invalid input syntax for type std::int64: "x" (22P02), value "99999" is out of range for type std::int16 and std::int64 out of range (22003), std::cal::local_date/std::cal::local_time field value out of range: "…" (22008). The SQLSTATE is PostgreSQL’s, unchanged: match on it, or on the SDK’s error class, rather than on the message.

A cast of a str fails as Gel’s does: <bool>'t' is invalid input syntax for type std::bool: 't' (only true and false are read), <Color>'Purple' is invalid input value for enum 'default::Color': "Purple" (22P02), and text that isn’t ISO 8601 cast to datetime, cal::local_datetime, cal::local_date or cal::local_time is invalid input syntax for type std::datetime: 'x' (22007) with Gel’s hint, Please use ISO8601 format. Example: 2010-12-27T23:59:59-07:00. …. The hint is extensions.hint over HTTP, the hint attribute of the binary protocol’s error, and hint on the SDK’s DiscQueryError. <bytes>'x' is the compile error cannot cast 'std::str' to 'std::bytes'.

extensions.queryHash on every response is the SHA-256 hex digest of the query text.

Disc Error Classes

All errors inherit from the abstract base class DiscError. Every error carries an optional ErrorContext (source snippet, source location, hint) and renders a fully-formatted multi-line message via formatError().

Gel Protocol Error Codes

These are the 32-bit codes Disc returns to binary-protocol clients. They are Gel’s codes (edb/api/errors.txt), so existing Gel SDKs pick the right error class — and know which errors to retry. Defined in protocol/binary-server.ts as GEL_ERROR_CODES.

The high byte is the family; subsequent bytes narrow within the family.

Server / protocol

Query

Execution

Configuration

Access and authentication

Availability

Backend

Class → Protocol Code Mapping

Performed by mapErrorToGelCode() in protocol/binary-server.ts. An error PostgreSQL raised is mapped by its SQLSTATE, as Gel does: 23502 → MissingRequiredError, 23000/23001/23503/23505/23514/23P01 (unique, foreign key, check, exclusion) → ConstraintViolationError, 21000 → CardinalityViolationError, 22012 → DivisionByZeroError, 22003/22015 → NumericOutOfRangeError, other 22xxx → InvalidValueError, 42501 (an access policy violation) → AccessPolicyError, 40001 → TransactionSerializationError, 40P01 → TransactionDeadlockError, 25006/25P02 → TransactionError, 57014 → QueryTimeoutError, 08xxx and 57P01–57P03 → BackendUnavailableError, 0A000 → UnsupportedBackendFeatureError; any other SQLSTATE → InternalServerError. Otherwise by class: