Errors

Two classes cover every transport failure, and five guards cover the coded refusals a tool result can carry. A method's own page says which of these it can throw; the rules are the same everywhere:

• A non-2xx answer from a method that talks to the backend directly (create, send, sendStream, proxyExecute, paymentStatus, verificationStatus, the two streams, authorize) throws CodesparApiError with the parsed body.
• A request that never reaches the backend (DNS, TLS, a refused connection) throws CodesparApiError with status: 0 and the original fetch rejection as cause.
• A request that exceeds its timeout throws TimeoutError. Streams use an idle timeout that resets on every complete SSE frame.
• execute does not throw for an HTTP error: it returns { success: false, error }. The typed wrappers (charge, ship, ledger, issue, shop, discover, connectionWizard) turn that into a plain Error whose message starts with the method name.
• connections and close swallow transport failures on purpose.

CodesparApiError

The structured exception for every backend answer the SDK refuses. Branch on code, never on the message text: the message is for logs and the SemVer promise covers status, code and body, not the wording.

try {
  await session.send("Charge R$150 via Pix");
} catch (e) {
  if (e instanceof CodesparApiError) {
    if (e.status === 0) console.error("network:", e.cause);
    else console.error(e.status, e.code, e.body);
  } else {
    throw e;
  }
}

interface CodesparApiErrorOptions {
  status: number;
  code?: string;
  body?: unknown;
  cause?: unknown;
}

class CodesparApiError extends Error {
  readonly status: number;
  readonly code?: string;
  readonly body?: unknown;
}

instanceof works across transpilers and realms: the constructor restores the prototype chain explicitly. The reserved code namespace is the hosted test-mode wire contract; code that extends this class should prefix its own codes (myapp.policy_denied).

Related Errors for the codes the API answers with, Debugging for what to quote (X-Request-Id first).

TimeoutError

Thrown when a unary request exceeds its total timeout, or a stream goes idle past it. timeoutMs is the budget that was exceeded. The class is on the core's main branch (the request-timeout-and-cancellation change) and not in the package on npm, where a timeout surfaces as the underlying abort.

import { TimeoutError } from "@codespar/sdk";

try {
  await session.paymentStatusStream("tc_0000000000000000", { timeout: 120_000 });
} catch (e) {
  if (e instanceof TimeoutError) console.error(`idle for ${e.timeoutMs} ms`);
}

class TimeoutError extends Error {
  readonly name: "TimeoutError";
  readonly timeoutMs: number;
}

Tool-result codes

A tool call the runtime refuses for a governed reason does not fail the HTTP request: it succeeds with a coded output. The five variants are inert wire shapes; the guards below turn unknown into one of them so a caller branches without casting. Each guard checks the code discriminant and the variant's required sibling fields, so a well-formed code with a missing rule_id returns false rather than narrowing on the discriminant alone.

TOOL_RESULT_CODES

The set of the five codes, for a membership test on a string.

ToolResultCode

Both a value (the five constants) and a type (their union). ToolResultCode.PolicyDenied is "policy_denied".

isPolicyDenied

isApprovalRequired

isMocksExhausted

isMocksEngineError

isToolNotMocked

assertExhaustiveToolResult

The exhaustiveness witness: pass the narrowed value in the default branch of a switch over ToolResultCode, and the file stops compiling the day a sixth variant lands without a handler. At runtime it throws, so a hostile cast does not silently pass an unknown code through.

for await (const event of session.sendStream("Pay R$1.50 to the example key")) {
  if (event.type !== "tool_result") continue;
  const out = event.toolCall.output;
  if (isPolicyDenied(out)) console.log("denied by rule", out.rule_id);
  else if (isApprovalRequired(out)) console.log("approval", out.approval_id, "until", out.expires_at);
  else if (isMocksExhausted(out) || isMocksEngineError(out)) console.log("mocks:", out.message);
  else if (isToolNotMocked(out)) console.log("no mock for", out.tool_name);
}

interface PolicyDeniedOutput { code: "policy_denied"; rule_id: string; message: string }
interface ApprovalRequiredOutput { code: "approval_required"; approval_id: string; expires_at: string; message: string }
interface MocksExhaustedOutput { code: "mocks_exhausted"; message: string }
interface MocksEngineErrorOutput { code: "mocks_engine_error"; message: string }
interface ToolNotMockedOutput { code: "tool_not_mocked"; tool_name: string; message: string }

type ToolResultOutcome =
  | PolicyDeniedOutput
  | ApprovalRequiredOutput
  | MocksExhaustedOutput
  | MocksEngineErrorOutput
  | ToolNotMockedOutput;

Related Test mode for mocks and strict mode, Guardrails for policies and approvals.