SDKs · Node.js

Node.js Types & Errors

Use exported TypeScript types and six instanceof-checkable error classes to make every outcome explicit. Keep retries narrow and treat interrupted writes as uncertain.

Public result families

Family	Examples	How to consume it
Memory interfaces	`MemoryRecord`, `QueryResponse`, `BulkAddResponse`, `ComposeResponse`	Use camelCase properties.
Add union	`MemoryRecord \| AddSkippedResponse`	Narrow with the `status` discriminator.
Control-plane interfaces	`LoginResponse`, `TeamMember`, `Webhook`, `AuditEventListResponse`	Use exported types and tolerate documented null or optional fields.
Delete result	`number[]`	Compare confirmed IDs with requested IDs.

Error classes

Class	Typical condition	Default action
`AuthError`	401 or 403	Fix authentication, permission, or scope.
`ValidationError`	400, 409, 422, or client validation	Correct the request; do not retry unchanged.
`NotFoundError`	404	Show an unavailable state without revealing other scopes.
`RateLimitError`	429	Use `retryAfterSeconds` and bound attempts.
`ServerError`	5xx	Retry safe reads with bounded backoff; reconcile writes.
`MemorySyncError`	Network, timeout, or other SDK failure	Treat mutation outcomes as uncertain.

Narrow errors with instanceof

handle-errors.ts

import {
  AuthError,
  MemorySyncError,
  NotFoundError,
  RateLimitError,
  ServerError,
  ValidationError,
} from "memorysync-sdk";

try {
  const memory = await client.get(101);
  console.log(memory.text);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Memory is unavailable in this scope");
  } else if (error instanceof AuthError || error instanceof ValidationError) {
    throw error;
  } else if (error instanceof RateLimitError) {
    console.log("Retry after", error.retryAfterSeconds);
    throw error;
  } else if (error instanceof ServerError) {
    throw error;
  } else if (error instanceof MemorySyncError) {
    throw error;
  } else {
    throw error;
  }
}

Retry reads narrowly

retry-read.ts

import { RateLimitError, ServerError } from "memorysync-sdk";

const sleep = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

async function queryWithRetry(question: string, attempts = 3) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await client.query({ query: question, k: 5 });
    } catch (error) {
      if (attempt === attempts - 1) throw error;
      if (error instanceof RateLimitError) {
        await sleep((error.retryAfterSeconds || 1) * 1000);
      } else if (error instanceof ServerError) {
        await sleep(250 * 2 ** attempt);
      } else {
        throw error;
      }
    }
  }
  throw new Error("unreachable");
}

Use error context defensively

Property	Type	Availability
`statusCode`	`number \| undefined`	Present when an HTTP response supplied a status.
`response`	`unknown`	Parsed response when one was available.
`requestId`	`string \| undefined`	Present only when the server returned a request identifier.
`retryAfterSeconds`	`number`	Available on `RateLimitError`.

Log a safe support record

logging.ts

import { MemorySyncError } from "memorysync-sdk";

try {
  await client.query({ query: "What preference applies?", k: 5 });
} catch (error) {
  if (error instanceof MemorySyncError) {
    console.warn("memory query failed", {
      statusCode: error.statusCode,
      requestId: error.requestId,
    });
  }
  throw error;
}

Related contracts

Rate Limits & Errors

Review shared status and recovery guidance.

Node.js Memory Client

See operation-specific result types.

Node.js Control Plane

Use typed administrative results.

Production Patterns

Apply uncertain-write and observability rules.

← Previous

Memory Client

Control Plane