> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# SQL drivers errors

The error classes thrown by @surrealdb/pg and @surrealdb/mysql, what each one means, and how the compatibility layers map statement failures to node-postgres, mysql2, Neon and PlanetScale errors.

Every error the native API throws extends `SurrealSqlError`, and every class is exported.

| Error | When |
| --- | --- |
| `StatementError` | A statement failed. It has `sqlstate`, `errno`, `severity`, `position` and the partial `results`. |
| `CapabilityDeniedError` | The instance denies the method or the dialect route, for example with `--deny-http postgres` or `--deny-rpc pgsql`. |
| `AuthError` | Sign-in or token failure. |
| `RpcError` | The call itself failed. It has `code`, `kind` and `details`. A "Method not found" reply means the instance may not serve the SQL RPC methods. |
| `ConnectionError`, `ConnectionLostError` | Network failure. `ConnectionLostError` has `inTransaction`. |
| `AbortError`, `TimeoutError` | The caller aborted, or the timeout elapsed. |
| `UnknownResponseError` | A reply that is not an RPC reply, such as a proxy page. It keeps the status and the first 4096 characters of the body. |
| `UnsupportedOnTransportError` | `begin` or `live` on a transport pinned to HTTP. |

```ts
import { connect, StatementError } from "@surrealdb/pg";

try {
    await sql`SELECT * FROM missing`;
} catch (error) {
    if (error instanceof StatementError && error.sqlstate === "42P01") {
        // the relation does not exist
    }
}
```

## Compatibility layers

The compatibility layers convert `StatementError` to the shape their ecosystem expects.

| Layer | Error | Fields |
| --- | --- | --- |
| node-postgres (`@surrealdb/pg`) | `DatabaseError` | `code` (the SQLSTATE), `severity`, `message`, `position` |
| mysql2 (`@surrealdb/mysql`) | `MysqlError` | `code`, `errno`, `sqlState`, `sqlMessage`, `sql` |
| Neon (`@surrealdb/pg/neon`) | `NeonDbError` | The node-postgres fields, and `sourceError` for failures before the instance answers |
| PlanetScale (`@surrealdb/mysql/planetscale`) | `DatabaseError` | `body.message`, `body.code`, `status`, `errno`, `sqlState` |

The mysql2 layer names the common error numbers (1045, 1048, 1049, 1050, 1051, 1054, 1062, 1064, 1146, 1205, 1213, 1216, 1217, 1317, 1451 and 1452), for example `ER_DUP_ENTRY` for 1062. Any other number gets the code `ER_UNKNOWN`, with the number in `errno`.

## Retries

The drivers never retry a write. A call that fails authentication in token mode is retried once with a fresh sign-in, and nothing else is retried.