Errors

Every failing call surfaces an SdkError: the async ones (sign, SignerClient.connect, the stream methods) reject their promise with it; the synchronous embed throws it directly. The verifier SDK throws the same shape.

SdkError is a discriminated union on kind:

type SdkError =
  | { kind: "reason";  code: Code; message: string; reason: string; domain: string; metadata: Record<string, string> }
  | { kind: "invalid"; code: Code; message: string; fieldViolations: FieldViolation[] }
  | { kind: "status";  code: Code; message: string };

interface FieldViolation { field: string; description: string; reason: string }

code (a coarse, machine-readable class — "invalid_argument", "resource_exhausted", "failed_precondition", …) and message (human-readable) are on every shape. Branch on kind:

try {
  await sdk.sign(bytes, title, manifest, options);
} catch (e) {
  const err = e as SdkError;
  switch (err.kind) {
    case "invalid":
      // The request was rejected — one entry per bad field.
      for (const v of err.fieldViolations) {
        console.error(`${v.field}: ${v.description} (${v.reason})`);
      }
      break;
    case "reason":
      // A semantic error — branch on the stable reason.
      if (err.reason === "SESSION_CONTINUATION_EXPIRED") restartSigning();
      else showError(err.message);
      break;
    case "status":
      // Usually retryable — check err.code.
      if (err.code === "unavailable") retryLater();
      break;
  }
}

kind: "invalid" — the request was rejected

The SDK validates your request locally before sending it, so a malformed request rejects immediately with the same fieldViolations the service would return — no round trip. Each violation names the offending field, a human description, and a stable reason (the constraint that failed, e.g. bytes.min_len or provenance.input_to.referenced) you can branch on.

kind: "reason" — a semantic error

Errors the request shape can't catch carry a single stable reason (SCREAMING_SNAKE_CASE). The code tells you how to react:

code	Example reason	Meaning
invalid_argument	PROVENANCE_INPUT_TO_REFERENCED, ASSERTION_LABEL_RESERVED, SOFT_BINDING_ALG_UNSUPPORTED, SUBMIT_HASH_KIND_MISMATCH	Fix the request.
resource_exhausted	SESSION_TOO_MANY	Too many signing sessions in flight — back off and retry.
failed_precondition	SESSION_CONTINUATION_EXPIRED, STORAGE_REMOTE_UNAVAILABLE	Restart the sign, or a service-configuration issue.
not_found	SESSION_CONTINUATION_UNKNOWN	The signing session was already used or never existed.
permission_denied	SESSION_CONTINUATION_FORBIDDEN	The signing session belongs to a different client.

Branch on reason, never on message — the human text may change; the reason is stable.

kind: "status" — no detail

A failure with no structured detail — the request didn't complete, or the service returned only a code. Inspect code ("unavailable", "deadline_exceeded") to decide whether to retry.