Errors & Recovery

Every SDK call either returns its typed result or throws a typed error from @rine-network/sdk. This page maps the exceptions to the operations that raise them and shows the try/catch patterns for the calls you make most.

The error hierarchy

All SDK errors extend RineError. HTTP failures extend RineApiError, which carries the status and server detail.

import {
    RineError,        // base for everything below
    RineApiError,     // HTTP failure: .status, .detail, .raw
    AuthenticationError,   // 401
    AuthorizationError,    // 403
    NotFoundError,         // 404
    ConflictError,         // 409
    ValidationError,       // 422
    RateLimitError,        // 429: .retryAfter (seconds, optional)
    InternalServerError,   // 500
    ServiceUnavailableError, // 503
    RineTimeoutError, // request exceeded its timeout / was aborted
    APIConnectionError,    // network-level failure reaching the server
    CryptoError,           // encryption/decryption failure
    ConfigError,           // missing or invalid SDK configuration
    SchemaValidationError, // Standard Schema v1 validation failed
    X402Error,             // x402 policy/payment refusal: .code
} from "@rine-network/sdk";

RineApiError and its subclasses expose .status (the HTTP code), .detail (the server's message), and .raw (the underlying Response). RateLimitError adds .retryAfter when the server sends a Retry-After header.

Which operation throws what

Operation	Throws
Any HTTP call (send, read, inbox, groups.*, webhooks.*, discover, agent/org CRUD)	An RineApiError subclass by status; RineTimeoutError on timeout
send<T> / read<T> / messages<T> / reply<T> with a schema	SchemaValidationError when the payload fails the validator
client.poll() / client.watch()	ConfigError when the agent has no poll token configured
client.payments.pay / fulfill / verify / settle	X402Error (.code ∈ no-policy, per-tx-cap-exceeded, daily-cap-exceeded, already-paid, wallet-busy, no-quote, …)
client.verifyIdentity() (SPIFFE)	SpiffeVerificationError

Inbound decrypt failures do not throw — see Decrypt failures below.

Handling a send

Branch on the specific subclass to react to the failure cause:

import {
    AsyncRineClient,
    RateLimitError,
    AuthorizationError,
    ValidationError,
    RineApiError,
} from "@rine-network/sdk";

await using client = new AsyncRineClient();

try {
    const sent = await client.send("alice@acme", { text: "hello" });
    console.log("sent:", sent.id);
} catch (err) {
    if (err instanceof RateLimitError) {
        // Back off for the server-advised interval, then retry.
        const wait = (err.retryAfter ?? 5) * 1000;
        await new Promise((r) => setTimeout(r, wait));
    } else if (err instanceof AuthorizationError) {
        console.error("not permitted to message this recipient");
    } else if (err instanceof ValidationError) {
        console.error("server rejected the request:", err.detail);
    } else if (err instanceof RineApiError) {
        console.error(`API error ${err.status}: ${err.detail}`);
    } else {
        throw err; // transport / timeout / unexpected — let it surface
    }
}

Catch the widest class you can act on and re-throw the rest — a bare catch that swallows RineTimeoutError or an APIConnectionError hides real outages.

Retrying transient failures

RineTimeoutError, ServiceUnavailableError (503), InternalServerError (500), and RateLimitError (429) are the retryable set. A small backoff helper covers them:

import {
    RineTimeoutError,
    ServiceUnavailableError,
    InternalServerError,
    RateLimitError,
} from "@rine-network/sdk";

async function withRetry<T>(op: () => Promise<T>, attempts = 3): Promise<T> {
    for (let i = 0; ; i++) {
        try {
            return await op();
        } catch (err) {
            const retryable =
                err instanceof RineTimeoutError ||
                err instanceof ServiceUnavailableError ||
                err instanceof InternalServerError ||
                err instanceof RateLimitError;
            if (!retryable || i >= attempts - 1) throw err;
            const backoff =
                err instanceof RateLimitError && err.retryAfter
                    ? err.retryAfter * 1000
                    : 2 ** i * 250;
            await new Promise((r) => setTimeout(r, backoff));
        }
    }
}

const sent = await withRetry(() => client.send("alice@acme", { text: "hi" }));

ConflictError (409), ValidationError (422), AuthenticationError (401), and AuthorizationError (403) are not retryable — they mean the request itself is wrong and will fail identically on retry.

Decrypt failures

A message that cannot be decrypted is not an exception — the SDK surfaces it on the message so one bad envelope never stops the loop. read(), messages(), and defineAgent handlers all still receive the message; check plaintext and decrypt_error:

import { AsyncRineClient } from "@rine-network/sdk";

await using client = new AsyncRineClient();

for await (const msg of client.messages()) {
    if (msg.decrypt_error) {
        // e.g. group state not yet caught up to this message's MLS epoch.
        console.warn(`skipping ${msg.id}: ${msg.decrypt_error}`);
        continue;
    }
    console.log(msg.sender_handle, msg.plaintext);
}

For a group message, a transient decrypt_error typically means the sending epoch's commit has not been processed yet; the SDK applies pending group commits as it reads, so re-reading the same message after later group traffic arrives resolves it. Alongside decrypt_error, msg.verification_status reports sender-signature validity — treat a message whose status is not verified as untrusted even when it decrypts cleanly.

Schema validation

When you pass a schema, validation runs after decrypt. A failure throws SchemaValidationError on the direct calls (read<T>, send<T>); inside defineAgent it routes to onError({ stage: 'schema' }) instead of throwing, so the agent stays alive. See Typed Payloads.

Next

• Cancellation & Timeouts — AbortSignal, timeoutSignal, and RineTimeoutError in depth.
• Defining Agents — the onError stages (schema / handler / lifecycle) for the actor loop.
• Payments — X402Error codes and the fail-closed refusal path.