Error reference

The Honua JS SDK exposes a tagged error envelope from @honua/sdk-js. Public errors migrated in the table below pass the cross-realm isHonuaError(error) guard. Use their stable classifications to gate retry, refresh, fallback, and surface-to-user decisions instead of parsing message strings.

This release covers core transport/auth/protocol errors, discovery, the query planner, every public error exported by the stable map and runtime subpaths, the public realtime resume error, and the offline region plus replica synchronization classes migrated by #569, plus the plugin registry error migrated by #571. Agent errors (#570) remain an explicit residual. Other experimental domains likewise retain their current domain-specific contracts until a scoped migration lands.

Envelope contract

Every migrated instance has these common fields:

Existing error-specific .code values remain compatible. For example, HonuaGrpcError.code is still the numeric gRPC status and HonuaDiscoveryError.code is still "invalid-endpoint" (or another legacy discovery code). Use .sdkCode when one globally unique value is required. serializeHonuaError(error) projects .sdkCode as the serialized envelope's .code.

Serialization is deliberately fail-closed. serializeHonuaError and JSON.stringify(error) include classification, identifiers, sanitized context, and classification-only cause information. They omit raw messages, stacks, response bodies, details, cause payloads, credentials, authorization/cookie headers, cached feature bodies, raw cursors/resume tokens, signed URL values, query/filter/SQL values, local storage paths, plugin manifests/configuration, tool payloads, cleanup failures, binary payloads, and prototype-manipulation keys. The raw instance still retains its message, documented detail fields, exact cause, and documented cleanup aggregates for local use.

import { isHonuaError, serializeHonuaError } from "@honua/sdk-js";

try {
  await operation();
} catch (error) {
  if (!isHonuaError(error)) throw error;
  console.error(serializeHonuaError(error));
  if (error.category === "cancellation") return;
  if (error.retryable) scheduleRetry();
}

At-a-glance table

Registered code families

The exported HONUA_ERROR_CODE_REGISTRY is the canonical, typed inventory. Its object keys are globally unique at compile time, the common base accepts only registered codes, and domain constructors either reject unknown runtime reasons or project them to a fixed registered fallback. Focused entrypoints retain only the code/domain/category/retryability classifications needed by the error base; human-readable registry summaries remain in the explicit public registry. npm run check:error-codes verifies exact classification parity, registry shape, and this class/family documentation.

HonuaRealtimeResumeError.code remains the existing detailed reason (for example, invalid-checkpoint, sequence-gap, transport-gap, or delivery-failed). Its sdkCode groups those reasons into stable recovery classes. realtime.transport.reconnectable and realtime.sequence.gap are marked retryable because the existing contract permits reconnect or replacement snapshot recovery; the envelope does not perform either action. SSE abort, unsubscribe, and close still complete normally without emitting an error.

HonuaOfflineRegionError.code and HonuaReplicaSyncError.code likewise retain their detailed legacy reasons. Their grouped sdkCode values distinguish invalid state, quota/storage, cancellation, integrity, capability, permission, and transport recovery classes. Generic resource/replica transport failures are non-retryable by default; offline.transport.transient is selected only when the wrapped cause is itself a valid tagged, retryable network or timeout error. Raw cached content, sync cursors, signed URLs, filter values, resource locators, details, and filesystem paths are kept on the local error instance only; serialization emits a fixed registered reason and classification. Retryability is descriptive and does not alter offline eviction, commit, transport, or conflict-resolution policy.

HonuaPluginRegistryError.code remains the existing PLUGIN_* reason and cleanupErrors remains a frozen shallow copy of cleanup failures. The grouped sdkCode distinguishes registry validation, compatibility, host-policy denial, missing capability, activation, execution validation, cleanup, cancellation, and internal failures. Every plugin classification is conservatively non-retryable. Serialization emits only the registered classification and a fixed known reasonCode; it never emits manifests, plugin/configuration IDs, raw cause payloads, or cleanup payloads. Unknown runtime codes project to plugin.internal with reasonCode: "PLUGIN_UNKNOWN" without changing a valid string's local legacy .code or message.

Individual code registry

Narrowing in catch

Prefer the isHonuaError guard so unrelated exceptions (e.g. caller TypeErrors in callbacks) propagate normally:

import { HonuaHttpError, HonuaTimeoutError, HonuaCapabilityNotSupportedError, isHonuaError } from "@honua/sdk-js";

try {
  await dataset.source("parcels")!.queryAll({ where: "1=1" });
} catch (error) {
  if (!isHonuaError(error)) throw error;

  if (error instanceof HonuaCapabilityNotSupportedError) {
    // expected for capability misses — fall back to a narrower query
    return fallbackQuery();
  }
  if (error instanceof HonuaHttpError && error.statusCode === 401) {
    await refreshCredentials();
    return retry();
  }
  if (error instanceof HonuaTimeoutError) {
    notifyUser("Server slow — try again in a moment.");
    return;
  }
  throw error;
}

Retry policy

The SDK's built-in retry (HonuaClientOptions.retry) automatically handles a subset of these errors when configured:

Capability policy

createDataset({ capabilityPolicy: "strict" }) is the default and is recommended for production. It surfaces capability misses as HonuaCapabilityNotSupportedError before the network call, so unsupported features can never silently degrade to an empty result. capabilityPolicy: "degraded" is intended for exploratory tools that prefer best-effort results with an explicit degraded reason annotated on the Result.