Reference

Common problems

Every failure below is something the SDK actually reports. Branch on error.code — never on the message text.

Symptoms

Symptom → cause
Parameter	Type	Required	Description
KEYCHAIN_UNAVAILABLE	HiveSdkError	No	Hive Keychain is not installed, or the call ran outside a browser (SSR, Node, a worker).
KEYCHAIN_REJECTED	HiveSdkError	No	The user declined the request in the Keychain popup.
KEYCHAIN_ERROR	HiveSdkError	No	Keychain returned an error: wrong authority, unknown account, or a broadcast rejection from the node.
RPC_ERROR / HTTP_ERROR	HiveSdkError	No	The node answered with a JSON-RPC error, or every endpoint in the fallback list failed.
NOT_FOUND	HiveSdkError	No	The transaction id does not exist yet, or it is older than the node's history window.
PARSE_ERROR	HiveSdkError	No	A payload could not be read as JSON.
VALIDATION_ERROR	HiveSdkError	No	An account name, token symbol, quantity or standardized payload failed validation before anything was broadcast.
ENV_VAR_MISSING / SIGNING_KEY_MISSING	HiveSdkError	No	A backend operation needs an account or key environment variable that is not set in this runtime.
BROADCAST_ERROR	HiveSdkError	No	The signed transaction was rejected by the node (insufficient resource credits, bad authority, duplicate transaction).

Keychain problems

Check availability before rendering a signing button. Availability is false during server rendering and stays false until the extension injects itself, so check it after hydration.

TypeScript

if (!hive.keychain.isAvailable()) {
  // Prompt the user to install Hive Keychain instead of calling a signing method.
}

try {
  await hive.keychain.customJson({ username, id: "my-app", action: "claim" });
} catch (error) {
  if (error instanceof HiveSdkError && error.code === "KEYCHAIN_REJECTED") {
    // The user cancelled — this is a normal outcome, not a bug.
  }
}

RPC problems

Public nodes rate-limit and occasionally lag. Pass a specific endpoint, or let Beacon pick healthy nodes, and retry read calls.

TypeScript

const nodes = await hive.beacon.getNodes();
const hive2 = new HiveClient({ endpoint: nodes[0]?.endpoint });

Payload problems

A malformed payload never crashes a watcher: it is simply not a standardized event. Use the validator to see exactly why.

TypeScript

import { validateActionPayload } from "hivexph-sdk";

const check = validateActionPayload(JSON.parse(json));
if (!check.valid) console.warn(check.reason);

Payment problems

A Layer 2 transfer that appears on Hive can still fail inside Hive Engine. Treat only status === "success" as settled; failed means the sidechain rejected the transfer, and pending means execution is not yet verifiable.

Important

Never deliver value on transaction inclusion alone. Wait for the validated status or the onSuccess callback of hive.payments.watch().