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. |
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.