Handle errors

@beblurt/dblurt preserves historical error names and messages for compatibility while adding structured classification metadata for applications that need safer retry and display decisions.

Use this guide when deciding whether to retry, fail over, surface validation feedback or stop a workflow.

Classify first

import { classifyError, isDBlurtError } from '@beblurt/dblurt';

try {
    await client.condenser.getAccounts(['beblurt']);
} catch (error) {
    const metadata = classifyError(error);

    if (metadata.retryable) {
        // retry or fail over according to your policy
    }

    if (isDBlurtError(error)) {
        console.error(metadata.category, metadata.code);
    }
}

Avoid string-matching arbitrary error messages when stable classification metadata is available.

Error categories

Category	Typical meaning	Common action
`validation`	SDK input rejected before RPC/broadcast	ask caller/user to fix input
`timeout`	request exceeded configured timeout	retry/fail over if workflow is a blockchain query
`transport`	network or HTTP-level failure	retry/fail over if safe
`rpc_application`	RPC node returned an application error	inspect code/data; retry only when justified
`serialization`	signing/serialization failed	fix payload/key handling
`unknown`	not recognized	fail safely and log non-sensitive context

Exact metadata fields belong to the API reference.

Query retries vs broadcast retries

Blockchain queries can often be retried with bounded backoff because they do not submit transactions.

Broadcast operations are different. A timeout after submission may be ambiguous. The transaction may have been accepted, rejected, still propagating or never received.

Workflow	Retry posture
blockchain query	retry/fail over when `retryable` and bounded
blockchain parsing	retry from last checkpoint when safe
operation builder	fix validation input; retry is usually not useful
broadcast operation	do not blindly retry; reconcile transaction context first

Validation errors

Validation errors are useful for user correction:

import { ValidationError } from '@beblurt/dblurt';

if (error instanceof ValidationError) {
    console.error(error.field, error.path);
}

Do not include private keys, signed payloads with sensitive context or secret environment values in logs.

RPC errors

RPC application errors come from a Blurt RPC endpoint. Preserve the distinction between:

a method or payload rejected by the node;
a transport problem reaching the node;
a timeout waiting for the response;
a mismatched or malformed JSON-RPC response.

This distinction matters for retry policy and user-facing messages.

Validated example

examples/node/classify-retryable-error.cjs

Handle errors ​

Classify first ​

Error categories ​

Query retries vs broadcast retries ​

Validation errors ​

RPC errors ​

Validated example ​

Related docs ​

API details ​