Handle errors

Every failure the SDK surfaces — query errors, mutation rejections, raw client results, bootstrap failures — is one type: CapxulError. This guide shows where it appears, how to render and branch on it, and the full public code catalog.

Before you start

• You have hooks running against a working provider (Getting started).

The error type

import { CapxulError, isCapxulError } from "@capxul/sdk";
import type { CapxulErrorCode, CapxulErrorDetails } from "@capxul/sdk";

CapxulError extends Error with structured fields:

Branch on code, never by parsing message — messages can change between releases; codes are the contract. Use isCapxulError(value) to narrow an unknown caught value.

Errors from query hooks

Query hooks are typed UseQueryResult<Data, CapxulError>, so error is a CapxulError — no casting:

"use client";

import { useCapxulPayments } from "@capxul/sdk-react";

function PaymentsList() {
  const payments = useCapxulPayments();

  if (payments.isError) {
    return <p role="alert">{payments.error.message}</p>;
  }
  // …
}

Remember the provider's defaults: queries retry twice before isError goes true (see TanStack Query integration).

Errors from mutation hooks

Mutations surface the same error two ways:

• mutation.error — for rendering inline, exactly like queries.
• mutateAsync — rejects with the CapxulError, for imperative handling in submit handlers. (mutate does not throw; it routes the error to mutation.error and callbacks.)

"use client";

import { isCapxulError } from "@capxul/sdk";
import { useCapxulPay } from "@capxul/sdk-react";

function PayForm({ email }: { readonly email: string }) {
  const pay = useCapxulPay();

  const handlePay = async () => {
    try {
      await pay.mutateAsync({
        to: { kind: "email", email },
        amount: { currency: "USD", value: "25.00", decimals: 6 },
      });
    } catch (cause) {
      if (isCapxulError(cause)) {
        switch (cause.code) {
          case "INSUFFICIENT_BALANCE":
            showTopUpPrompt();
            return;
          case "RATE_LIMITED": {
            const retryAfterMs = cause.details?.retryAfterMs;
            scheduleRetry(typeof retryAfterMs === "number" ? retryAfterMs : 10_000);
            return;
          }
          default:
            showToast(cause.message);
            return;
        }
      }
      throw cause;
    }
  };

  return (
    <button type="button" onClick={() => void handlePay()} disabled={pay.isPending}>
      Pay $25
    </button>
  );
}

Mutations never retry automatically (retry: 0) — a failed money movement is yours to re-drive deliberately.

Errors from the raw client

The core client never throws for operational failures. Every method returns a CapxulResult<T> — a discriminated union:

type CapxulResult<T> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly error: CapxulError };

const result = await client.payments.list();
if (!result.ok) {
  console.error(result.error.code, result.error.message);
  return;
}
render(result.value);

When you wrap raw client calls in your own TanStack queries, throw result.error so the hook's error field carries the same type as the first-class hooks — see Drop to the raw client.

Bootstrap errors

If the provider's startup fails (bad key, unreachable backend, disallowed origin), no hook ever leaves its pending state. The failure lives on useCapxul:

"use client";

import { useCapxul } from "@capxul/sdk-react";

function BootstrapGate({ children }: { children: React.ReactNode }) {
  const bootstrap = useCapxul();

  if (bootstrap.status === "error") {
    return (
      <div role="alert">
        <p>{bootstrap.error?.message ?? "Capxul failed to start."}</p>
        <button type="button" onClick={bootstrap.retry}>
          Retry
        </button>
      </div>
    );
  }
  return children;
}

retry() re-runs the bootstrap in place. Do not rebuild the provider or the client yourself.

One related code you may see from mutations: firing a mutation while the provider is still bootstrapping rejects with WRONG_STATE (details.currentState: "bootstrapping"). Query hooks do not have this problem — they stay disabled until the client is ready.

The error-code catalog

The public catalog is a closed set — every SDK failure maps to one of these codes:

CapxulErrorCode is the exported union of exactly these strings, so an exhaustive switch over codes type-checks.

Practical rules

• Show error.message. It is written to be user-safe; you do not need a message map to ship.
• Branch on error.code, and on details for code-specific data.
• Log correlationId with any error you report — it is the join key to backend telemetry.
• Let queries retry, re-drive mutations yourself. The defaults already encode this.