Errors
QubicRpcError and QubicError — structure, properties, and handling patterns.
The live and archive clients use the Result<T, E> pattern rather than exceptions. Methods return { ok: false, error: QubicRpcError } on failure. Check result.ok before accessing result.value.
QubicRpcError is thrown directly only when you call unwrap() on an Err result yourself, or in unexpected situations like JSON parse failures.
QubicRpcError
Extends QubicError. Carries the HTTP status code and the endpoint path that failed.
import { QubicRpcError } from "@qubic.org/rpc"
const result = await live.getTickInfo()
if (!result.ok) {
const e = result.error
console.error(`RPC error ${e.status} on ${e.endpoint}: ${e.message}`)
}Properties
| Property | Type | Description |
|---|---|---|
message | string | Human-readable description of the failure |
status | number | HTTP status code. -1 for network errors and timeouts |
endpoint | string | The request path that failed (e.g. /tick-info) |
code | "RPC_ERROR" | Discriminant for narrowing the error type |
QubicError
Base class for all errors in the Qubic SDK. Exported from @qubic.org/types and re-exported from @qubic.org/rpc.
import { QubicError } from "@qubic.org/rpc"
if (e instanceof QubicError) {
// Covers QubicRpcError and any other SDK error
}Use instanceof QubicError when you want to catch any SDK error. Use instanceof QubicRpcError when you need the status and endpoint fields.
Common status codes
| Status | Meaning |
|---|---|
404 | Transaction or identity not found in the archive |
429 | Rate limit exceeded |
500 | Gateway or node error |
-1 | Network unreachable, DNS failure, request timeout, or aborted |
Retry pattern
import { createLiveClient, QubicRpcError } from "@qubic.org/rpc"
const live = createLiveClient()
async function withRetry<T>(
fn: () => Promise<{ ok: true; value: T } | { ok: false; error: QubicRpcError }>,
retries = 3,
): Promise<T> {
for (let i = 0; i < retries; i++) {
const result = await fn()
if (result.ok) return result.value
if (result.error.status === 429 && i < retries - 1) {
await new Promise((r) => setTimeout(r, 1000 * (i + 1)))
continue
}
throw result.error
}
throw new Error("unreachable")
}
const info = await withRetry(() => live.getTickInfo())Error models by package
Different packages in the Qubic SDK use different error conventions:
| Package | Error model |
|---|---|
@qubic.org/rpc | Result<T, QubicRpcError> — check result.ok |
@qubic.org/bob | Result<T, BobRpcError> — check result.ok |
@qubic.org/events | throws EventDecodeError |
@qubic.org/types constructors | throws typed QubicError subclass |