Errors

SDK methods reject with a standard Error whose message identifies the case. HTTP failures throw an HttpError carrying the status. Channel operations throw typed errors you can branch on.

Channel errors

import { ChannelNotFoundError, ChannelExistsError } from "@muhkoo/connect";

try {
  await client.space.joinChannel("project-x");
} catch (err) {
  if (err instanceof ChannelNotFoundError) {
    // No channel with that name — offer to create it.
    await client.space.createChannel("project-x");
  }
}

• ChannelNotFoundError — joinChannel(name) when the name isn’t registered. (carries .channelName.)
• ChannelExistsError — createChannel(name) when the name is already taken — join it instead.

HttpError

import { HttpError } from "@muhkoo/connect";

try {
  await client.kv.get("todos", "t1");
} catch (err) {
  if (err instanceof HttpError) {
    console.log(err.status); // e.g. 401, 402, 404
    console.log(err.body);   // parsed JSON error body, if any
  }
}

Common cases

Where	Message / status contains	Cause & fix
login	commitment mismatch / incorrect password	Wrong password, or a legacy/incompatible account.
login	User not found	No account with that username.
login	challenge	Auth challenge expired/replayed — retry.
storage	not signed in	No session — login() / restore() first.
storage	identity	Encrypted op needs an unlocked identity — login() or unlock(password).
message	not signed in	Messaging needs a signed-in user.
message	target must be 'user:…'	send() only takes user:<id> targets; use publish() for pub/sub.
any request	HttpError 401 — API key required	App key missing/invalid, or minted against a different deployment (keys are per-environment).
any request	HttpError 402	Usage quota exceeded for the app’s tier.

Defensive patterns

// Restore on boot without throwing on a stale token:
const user = await client.auth.zk.restore().catch(() => null);

// Gate encrypted reads on an unlocked identity:
if (client.auth.zk.identity) {
  const data = await client.kv.get("notes", id);
}