Error Handling

The SDK throws typed error classes that mirror the server’s error codes. All errors extend LocalVectorDBError, so you can catch broadly or narrowly.

Error Hierarchy

LocalVectorDBError (base)
├── ValidationError              (400)
├── AuthenticationError           (401)
├── PermissionError               (403)
├── NotFoundError                 (404)
│   ├── DatabaseNotFoundError
│   └── DocumentNotFoundError
├── ConflictError                 (409)
│   ├── DuplicateDocumentError
│   └── DatabaseAlreadyExistsError
├── ServiceUnavailableError       (503)
│   ├── EmbeddingError
│   ├── OllamaNotAvailableError
│   └── DatabaseConnectionError
├── ServerError                   (500)
│   └── ConfigurationError
├── ConnectionError               (network failures)
└── TimeoutError                  (request timeout)

Catching Errors

Use instanceof to catch specific error types:

import {
  DatabaseNotFoundError,
  DocumentNotFoundError,
  AuthenticationError,
  DuplicateDocumentError,
  ConnectionError,
  TimeoutError,
  LocalVectorDBError,
} from "@localvectordb/sdk";

try {
  await db.get("nonexistent-doc");
} catch (err) {
  if (err instanceof DocumentNotFoundError) {
    console.log("Document does not exist");
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (err instanceof ConnectionError) {
    console.log("Cannot reach server:", err.message);
  } else if (err instanceof TimeoutError) {
    console.log("Request timed out");
  } else if (err instanceof LocalVectorDBError) {
    // Catch-all for any server error
    console.log(`Error [${err.code}]: ${err.message}`);
  }
}

Catch a category with the parent class:

import { NotFoundError } from "@localvectordb/sdk";

try {
  await db.get("doc-id");
} catch (err) {
  if (err instanceof NotFoundError) {
    // Catches both DatabaseNotFoundError and DocumentNotFoundError
  }
}

Error Properties

Every LocalVectorDBError carries these properties:

Property	Type	Description
message	string	Human-readable error description
code	string	Machine-readable error code (e.g. "DATABASE_NOT_FOUND")
statusCode	number	HTTP status code (0 for network errors)
details	object	Additional context from the server (e.g. { field: "query" })
recoverable	boolean	Whether retrying might succeed
requestId	string | undefined	Server request ID for debugging
timestamp	string | undefined	ISO 8601 timestamp of the error

Retry Behavior

The SDK’s built-in retry logic (configured via maxRetries and retryDelay) only applies to:

• 5xx server errors — retried with exponential backoff

• Network errors — retried with exponential backoff

• Timeouts — retried with exponential backoff

4xx client errors are never retried — they indicate a problem with the request itself (bad input, missing auth, document not found, etc.).

The recoverable property on error objects reflects the server’s assessment of whether the error is transient. You can use it for application-level retry decisions:

try {
  await db.upsert(documents);
} catch (err) {
  if (err instanceof LocalVectorDBError && err.recoverable) {
    // Server says this might work if we try again
    await retry(() => db.upsert(documents));
  } else {
    throw err;
  }
}