TypeScript SDK errors

The SDK separates expected protocol outcomes from failures. Missing, stale, malformed, or invalid ZeroClick signatures are expected protocol outcomes, not exceptions. guard and guardIdentity return a deny decision that carries the exact Response to return. The lower-level verifyRequest returns { ok: false, reason, response }. Business denials (allowed: false from the allowance API) are deny decisions too. Malformed inputs, ZeroClick API failures, signing-secret resolution failures, and encryption failures throw ZCError.

ZCError

ZCError extends Error with a machine-readable code and a sanitized context:

class ZCError extends Error {
  readonly name: "ZCError";
  readonly code: ZCErrorCode;
  readonly context: {
    operation: string; // the SDK operation that failed
    issues?: { code: string; message: string; path: (string | number)[] }[];
    kid?: string;
    reason?: string;
    status?: number;
  };
}

context contains only sanitized operational fields: the operation, status, reason, key id, and validation issue paths. It never includes API keys, signing secrets, or request body bytes, so it is safe to log and is what onAllowanceUnavailable receives.

Narrowing with isZCError

Use isZCError to narrow an unknown error, optionally to one error code:

import { isZCError } from "@zeroclickai/sellers";

try {
  await zeroClick.reportUsage({
    zcAgentId: "agt_x7f2kq93bh0d",
    idempotencyKey: "zcreq_8h2m4x0q9k1f_output_tokens",
    serviceSlug: "product-watch",
    meterSlug: "output_tokens",
    quantity: 4200,
  });
} catch (error) {
  if (isZCError(error, "api_status_error")) {
    console.error(error.code, error.context.status, error.context.reason);
  }
  throw error;
}

isZCError(error) narrows to ZCError; passing a code narrows further, at runtime and in types: inside the branch, error is ZCError & { code: "api_status_error" }.

Error codes

Sixteen codes cover the SDK. The first seven come from the core package; only the @zeroclickai/sellers/encryption subpath throws the nine JWE codes.

Core codes

Code	Meaning
`malformed_input`	An SDK input failed validation: configuration, guard input, usage items, or call options. `context.issues` lists each violation’s path.
`malformed_request`	The value passed as the request is not a usable web-native `Request`, or the SDK could not clone and read its body.
`crypto_unavailable`	The runtime provides no Web Crypto (`globalThis.crypto.subtle`), so the SDK cannot verify signatures.
`signing_secret_resolution_failed`	The signing-secret resolver threw or returned an unusable value. Returning `null` for an unknown `kid` is not an error: the SDK denies that request as `unknown_kid`.
`api_transport_error`	The call to the ZeroClick API failed or timed out before any response arrived.
`api_status_error`	The ZeroClick API answered with an unsuccessful status. `context.status` carries it; `reportUsage` denials add `context.reason`.
`api_response_invalid`	The ZeroClick API answered, but with a body the SDK could not parse or validate.

JWE codes

Code	Meaning
`invalid_compact_jwe`	The request body is not a valid Compact JWE.
`unsupported_jwe_suite`	The JWE does not use the fixed `ECDH-ES+A256KW` / `A256GCM` suite.
`jwe_kid_required`	The JWE protected header carries no key id to resolve a private key by.
`invalid_reply_jwk`	The buyer’s reply JWK is not a public P-256 key.
`private_reply_jwk`	The reply JWK contains private-key material, so the SDK rejects it.
`private_key_not_found`	The resolver returned no private key for the JWE’s key id.
`private_key_resolution_failed`	The private-key resolver threw or returned an unusable value.
`decryption_failed`	The SDK could not decrypt the Compact JWE with the resolved key.
`encryption_failed`	The SDK could not encrypt the response body for the buyer’s reply key.

What throws where

Operation	Codes it can throw
`createSeller`	`malformed_input`, when the config violates the one-secret-source rule or leaves a usage direction without a key.
`verifyRequest`, `guard`, `guardIdentity` (verification step)	`malformed_input`, `malformed_request`, `crypto_unavailable`, `signing_secret_resolution_failed`. Signature outcomes never throw.
`guard` (allowance step)	`api_transport_error`, `api_status_error`, `api_response_invalid`, routed through the outage policy. The default `"allow"` converts them into an allow with `allowance.status: "unavailable"`, surfacing them only to `onAllowanceUnavailable`. `"deny"` converts them into the `503`, and `"throw"` rethrows them.
`checkAllowance`	`malformed_input`, `api_transport_error`, `api_status_error`, `api_response_invalid`.
`reportUsage`	Same as `checkAllowance`. On a `402`, `404`, or `409` denial, `context.reason` carries the machine reason, such as `usage_exhausted` or `meter_not_priced`.
`paymentRequired`, `withUsage`	`malformed_input`, including a `withUsage` call on an already-read `Response`.
`decryptRequest`	`malformed_input`, `malformed_request`, and every JWE code except `encryption_failed`.
`encryptResponse`	`malformed_input`, `encryption_failed`.

A duplicate usage report is not an error: reportUsage resolves with duplicate: true and replays the stored event. Only denials and infrastructure failures throw.

The error reference documents the wire-level error envelope behind api_status_error.

Overview

TypeScript

Python

Go

TypeScript SDK errors

ZCError

Narrowing with isZCError

Error codes

Core codes

JWE codes

What throws where

​ZCError

​Narrowing with isZCError

​Error codes

​Core codes

​JWE codes

​What throws where

ZCError

Narrowing with isZCError

Error codes

Core codes

JWE codes

What throws where