Handle errors

Every failure the SDK surfaces — query errors, mutation rejections, direct Core SDK 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">{"Could not load payments. Please try again."}</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("Payment failed. Please try again.");
            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 Core SDK 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 Core SDK 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 Call the Core SDK directly.

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>{"Capxul failed to start. Please try again."}</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.

Who acts: the failure class

failureClass(error) tells you who must act on a failure. It is derived from code and mode, so it never disagrees with them:

import { FAILURE_CLASSES, failureClass } from "@capxul/sdk";
import type { FailureClass } from "@capxul/sdk";

A code with one meaning always has the same class: INVALID_INPUT is input, PROVIDER_RESPONSE_INVALID is provider-answer and UNKNOWN is defect. PROVIDER_ERROR, NETWORK_ERROR, TRANSACTION_FAILED and EMAIL_DELIVERY_FAILED take their class from mode; with no mode they are defect. Map the codes you know first, then use the class to choose the copy for the rest.

Practical rules

• Use application-owned display copy. Error messages are diagnostic text.
• 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.
• Report a failure to PostHog with failureProperties. failureProperties(error, { operation, text: "full" }) from @capxul/sdk builds the same row the SDK and the backend send, with every string masked. text: "none" keeps closed facts only, for a surface that must send no free text.
• Let queries retry, re-drive mutations yourself. The defaults already encode this.

The public catalog also includes these lifecycle outcomes:

Use code, mode and chain to choose recovery. Applications supply display copy. Native cause objects stay local; the canonical serialized error carries only the declared diagnostic fields, and the backend masks every credential in its message and details before the error crosses the wire.