paybondpaybond
Sign in

TypeScript quickstart

Start with Paybond's one-command sandbox guardrail scaffold, then open a Kit session in TypeScript for production intent, capability, and evidence flows.

Sandbox agent middleware? Start with Agent quickstart — login, CLI smoke, and paybond.agent() with no signing keys. This page covers the full production intent lifecycle.

Plan choice: sandbox integration = Free Developer; low-volume production = Pay as you go.

For a first paid-tool guardrail integration, start with the sandbox scaffold:

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

This Free Developer path is sandbox-only. It bootstraps a sandbox guardrail intent, wraps your paid-tool handler, submits simulator evidence, and does not generate a paid-tool implementation. See One-command guardrails for the focused walkthrough.

For multi-tool agents, prefer paybond.instrument() — loads policy and returns deferred tool shells by default; bind per session with .bind() or pass a context provider for request-scoped binding. See Agent middleware. For the fastest sandbox path, use paybond.agent() (opt-in sandbox bootstrap).

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

try {
  const instrumented = await paybond.instrument({
    policy: "./paybond.policy.yaml", // or preset id "travel"
    tools: {
      premium_search: (input) => paidProvider.search(input),
    },
    sandbox: true, // local dev: immediate sandbox runtime; omit for deferred production bind
  });
  const tools = instrumented.tools;

  // Register `tools` with your agent runtime (OpenAI, LangGraph, MCP, custom).
  // Production: omit sandbox; call instrumented.bind({ intentId, capabilityToken }) per session.
} finally {
  await paybond.aclose();
}

For an existing bound run, use paybond.wrapTools(run, tools). Per-tool guardTool remains available for single-handler integrations — see Agent integrations.

This quickstart shows the standard Paybond application flow in TypeScript:

  1. Open an authenticated session against the Gateway with a service-account API key.
  2. Create a principal-signed intent (or bootstrap a sandbox guardrail for the first path).
  3. Read the funded intent's capability_token from create, fund, or bootstrap — see Capabilities.
  4. Verify that capability before tool work with paybond.spendGuard(intentId, capabilityToken).
  5. Submit signed evidence so Harbor can evaluate the predicate and transition the intent.

Every call below is tenant-scoped. The tenant comes from the Gateway exchange and is bound to the returned client, so you never pass a tenant ID by hand.

allowedTools should contain your application's own operation names. Paybond does not define that catalog; Harbor simply checks that the later authorizeSpend({ operation }) or verifyCapability({ operation }) call matches one of the names attached to the intent.

For the full API surface, see the TypeScript SDK reference.

Prerequisites

  • Node.js 22+ (global fetch, crypto.randomUUID).
  • A paybond_sk_sandbox_… or paybond_sk_live_… service-account API key issued for your tenant realm. For local sandbox work, run npx -p @paybond/kit paybond login; live production keys are created in Console by tenant admins and stored in your deployment secret manager.
  • For the principal-signed intent create flow: a 32-byte Ed25519 seed for the principal and a 32-byte seed for the payee bound to the intent. The Kit validates seed length in paybond.intents.create and paybond.intents.submitEvidence.

Install

Install the public package:

npm install @paybond/kit

For a fuller runnable application, see the TypeScript example projects.

Sandbox login

npx -p @paybond/kit paybond login

The login CLI starts a sandbox device approval flow, writes PAYBOND_API_KEY to .env.local with file mode 0600, adds the default .env.local target to .gitignore when needed, and refuses to overwrite an existing key unless --force is passed. Custom env-file paths inside a git repo must already be ignored. It prints the masked key identity and target sandbox tenant only; it never prints the raw key after writing.

Authenticated session

Paybond.open resolves the tenant realm from the hosted Gateway and returns tenant-bound Gateway, Harbor, Signal, fraud, A2A, and protocol clients. The examples below assume a sandbox key; set expectedEnvironment to "live" when using a paybond_sk_live_… key. The paybond.harbor property is created by Paybond.open(...); use paybond.spendGuard(...) for normal tool guards and paybond.harbor directly only for lower-level Harbor calls.

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

try {
  console.log("tenant realm:", paybond.harbor.tenantId);
} finally {
  await paybond.aclose();
}

Key properties of the session:

  • Tenant is derived, not supplied. The tenant realm is whatever the Gateway echoes. Do not read the tenant from request bodies or environment variables at call time.
  • Gateway is the public surface. Harbor operations go through Gateway's tenant-scoped /harbor and /verify routes.
  • Sessions are single-tenant. Construct one Paybond instance per (tenant, service account). Never share across tenants or reuse across concurrent runs bound to different intents.
  • Release resources. Always finish with await paybond.aclose() when the session is done. Paybond.open throws GatewayAuthError on any gateway or token failure.

Capability token source

Normal integrations do not supply capability tokens through environment variables. The token comes from the intent lifecycle. See Capabilities for the full reference, agent-run lifecycle, and incorrect integration patterns.

PathSDK callWhen you get capability_token
Sandbox first integrationpaybond.guardrails.bootstrapSandbox(...)Immediately in the bootstrap response
Production immediate fundpaybond.intents.create(...)When the selected rail funds in the create response
Production delayed / x402paybond.intents.fund(...)After funding succeeds (capabilityToken)

Additional notes:

  • paybond.spendGuard(...).authorizeSpend(...) and lower-level verifyCapability calls go through Gateway POST /verify. A 200 response with allow: false is a business denial, not an HTTP transport error.
  • paybond.intents.submitEvidence signs the payee evidence binding and posts it to Gateway POST /harbor/intents/{id}/evidence. Reuse the same idempotencyKey when retrying the same submission.
  • The client validates tenant and intent echoes on protected reads and writes so mismatched responses fail closed.
  • If you do not pass intentId to create, read the generated id from created.intent_id.
  • There is no POST /v1/capabilities/issue route. Do not use process.env.CAPABILITY_TOKEN in production agent runs.
  • Keep payeeSigningSeed in a secret manager. The value must be exactly 32 bytes and must correspond to the payee key bound on the intent.

Recognition proofs

Every Gateway-backed intent mutation in these snippets takes a recognitionProof. Think of it as a short-lived signature that says: "this tenant-registered agent key is authorizing this exact Gateway request right now."

Paybond does not create or hand this proof to your app, and Kit does not generate it automatically. The proof is created by your trusted backend, KMS-backed signer, wallet service, or agent runner:

  1. A tenant admin registers the agent runtime's Ed25519 public key in Paybond's trusted agent key registry and assigns it a stable key_id.
  2. Your trusted component keeps the matching Ed25519 private key. Do not expose that key to a browser, model prompt, or untrusted tool.
  3. Immediately before a protected mutation, that component signs a fresh AgentRecognitionProofV1 for the exact request.
  4. Kit base64url-encodes the finished proof object and sends it as x-paybond-agent-recognition-proof.
  5. Gateway verifies the signature against the registered public key, checks tenant/purpose/request binding, and rejects replayed nonces.

A typical app keeps this behind an internal helper or endpoint:

type IssueAgentRecognitionProofV1 = (input: {
  purpose: "harbor.intent.create" | "harbor.intent.fund" | "harbor.intent.evidence.submit";
  method: "POST";
  path: string;
  body: Record<string, unknown>;
}) => Promise<AgentRecognitionProofV1>;

Generate a fresh proof after the request body is fixed:

SDK callPurposeRequest envelope
paybond.intents.create(...)harbor.intent.createPOST /harbor/intents, SHA-256 digest of the signed create body
paybond.intents.fund(...)harbor.intent.fundPOST /harbor/intents/{intentId}/fund, SHA-256 digest of the empty object body
paybond.intents.submitEvidence(...)harbor.intent.evidence.submitPOST /harbor/intents/{intentId}/evidence, SHA-256 digest of the signed evidence body

Because the proof covers the body digest, the proof issuer must run where it can see or reproduce the final request body. If you prebuild Harbor bodies outside the high-level helpers, send them through the lower-level Gateway Harbor methods such as paybond.harbor.createIntent(...) and paybond.harbor.submitEvidence(...).

Each proof should include schema_version: 1, kind: "paybond.agent_recognition_proof_v1", the tenant-registered key_id, signature_algorithm: "ed25519-sha256-json-v1", verifier_context.tenant_id: paybond.harbor.tenantId, verifier_context.verifier_id: "paybond-gateway", a request envelope, a unique nonce, a short issued_at / expires_at window of 10 minutes or less, and the Ed25519 digest/signature fields.

Only PAYBOND_API_KEY is Paybond-issued in these examples. The APP_* environment variables below are local sandbox/live quick-start placeholders for values owned by your application, such as signing seeds, rail choices, wallet signatures, and proof JSON returned by your signer. They are not static production config. Production code should call your proof issuer for each create, fund, fund retry, and submitEvidence request.

Principal-signed intent create

paybond.intents.create builds a principal-signed intent body and submits it through Gateway POST /harbor/intents. intentId can default to crypto.randomUUID() when omitted, but this quickstart passes it explicitly so the recognition proof can bind to a stable request. The example below creates the intent, reads its returned capability token, verifies the tool operation, and submits evidence.

import { Buffer } from "node:buffer";
import { Paybond } from "@paybond/kit";

function seed32FromHex(hex: string): Uint8Array {
  const buf = Buffer.from(hex.replace(/^0x/i, ""), "hex");
  if (buf.length !== 32) {
    throw new Error("seed must be 32 bytes (64 hex characters)");
  }
  return new Uint8Array(buf);
}

const principalSeed = seed32FromHex(process.env.APP_PRINCIPAL_SEED_HEX!);
const payeeSeed = seed32FromHex(process.env.APP_PAYEE_SEED_HEX!);

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

try {
  const intentId = crypto.randomUUID();
  const createRecognitionProof = JSON.parse(process.env.APP_INTENT_CREATE_RECOGNITION_PROOF_JSON!);
  const created = await paybond.intents.create({
    principalDid: "did:web:example.com#principal",
    principalSigningSeed: principalSeed,
    recognitionProof: createRecognitionProof,
    payeeDid: "did:web:example.com#booker-agent",
    budget: { currency: "usd", max_spend_usd: 200 },
    predicate: { version: 1, root: { op: "true" } },
    currency: "usd",
    amountCents: 20_000,
    evidenceSchema: { type: "object" },
    deadlineRfc3339: "2030-12-31T23:59:59Z",
    allowedTools: ["travel.planner.plan", "travel.booker.purchase"],
    settlementRail: "stripe_connect",
    intentId,
    idempotencyKey: `intent:${intentId}`,
  });

  if (String(created.intent_id) !== intentId) {
    throw new Error(`intent mismatch: requested=${intentId} gateway=${String(created.intent_id ?? "")}`);
  }

  const capabilityToken = String(created.capability_token ?? "");
  if (!capabilityToken) {
    throw new Error("intent created without capability_token; fund the intent before verifying tools");
  }

  const guard = paybond.spendGuard(intentId, capabilityToken);
  const verified = await guard.authorizeSpend({
    operation: "travel.booker.purchase",
    requestedSpendCents: 18_700,
  });
  if (!verified.allow) {
    throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
  }

  // Only run the real action after Paybond authorizes the agent to do it.

  const submittedAtRfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
  const evidenceRecognitionProof = JSON.parse(process.env.APP_EVIDENCE_RECOGNITION_PROOF_JSON!);
  await paybond.intents.submitEvidence({
    intentId,
    payeeDid: "did:web:example.com#booker-agent",
    payeeSigningSeed: payeeSeed,
    recognitionProof: evidenceRecognitionProof,
    payload: { flight_booked: true, price: 187, confirmation: "PNR-4GH271" },
    artifactsBlake3Hex: [],
    submittedAtRfc3339,
    idempotencyKey: `evidence:${intentId}`,
  });
  console.log("created intent", intentId);
} finally {
  await paybond.aclose();
}

Choose intentId, submittedAtRfc3339, and idempotency keys before issuing request-bound recognition proofs so your signer can bind to the same request the SDK will send.

Managed-policy intent creation is not wrapped by this helper. If you need registry-bound signing, use paybond.harbor.createIntent with a pre-built body, request-bound recognition proof, and the Harbor policy registry.

allowedTools is your namespace, not Paybond's. For example, if your runtime later verifies operation: "travel.booker.purchase", that exact string must appear in the intent allow-list.

settlementRail is required and principal-signed. It requests one allowed rail such as stripe_connect, stripe_ach_debit, stripe_mpp, adyen_manual_capture, or x402_usdc_base; you are not supplying a Stripe destination, MPP profile id, Adyen merchant credentials, or x402 receive address. Harbor resolves the destination from the tenant's canonical settlement config and snapshots it onto the intent. For stripe_mpp, tenant admins configure the MPP profile (and optional Tempo session settings) in Configure settlement rails before enabling the rail. For adyen_manual_capture, configure the BYO Adyen destination in Configure Adyen settlement and confirm with paybond adyen ready / paybond adyen doctor.

Intent pricing remains USD-denominated even on the stablecoin rail: keep budget.currency and currency as "usd" with cent-based amounts, while x402_usdc_base tells Harbor to settle that value in USDC on Base.

Sandbox → production

After sandbox guardrails or agent middleware work locally, move to production intents with policy_binding (signing v7). The flow:

  1. Scaffold policy — paybond policy init --preset travel writes paybond.policy.yaml with intent.policy_binding.template_id aligned to your completion preset.
  2. Publish template head — In Console or via paybond policy templates and preview, publish the managed template head for your tenant. Record template_id, version_seq, materialized_predicate, and policy_content_digest_hex.
  3. Create intent — Use PaybondPolicy.toIntentCreateInput() and paybond.intents.createWithPolicyBinding() so Harbor binds the published predicate at create time.
  4. Fund and attach — Fund if the rail requires it, then bind agent middleware with productionEvidence (see Production attach).
import { Paybond, PaybondPolicy } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "live",
});

try {
  const policy = await PaybondPolicy.load("./paybond.policy.yaml");
  const publishedHead = {
    templateId: "completion_budget_v1",
    versionSeq: 1,
    materializedPredicate: { /* from publish response */ },
    policyContentDigestHex: "<digest_hex>",
  };
  const intentInput = policy.toIntentCreateInput({
    principalDid: process.env.APP_PRINCIPAL_DID!,
    principalSigningSeed: principalSeed32,
    payeeDid: process.env.APP_PAYEE_DID!,
    payeeSigningSeed: payeeSeed32,
    deadlineRfc3339: "2030-12-31T23:59:59Z",
    settlementRail: "stripe_connect",
    recognitionProof: await issueRecognitionProof({ purpose: "harbor.intent.create", /* ... */ }),
    publishedPolicyHead: publishedHead,
  });
  const created = await paybond.intents.createWithPolicyBinding(intentInput);
  // Fund if needed, then attach middleware or call spendGuard and submitEvidence.
} finally {
  await paybond.aclose();
}

Init scaffolds (paybond-init --preset agent-middleware, paybond init completion, and paybond init wizard stubs) include a commented production block with the same pattern. For the sandbox-only first path, see One-command guardrails.

Settlement rail and completion preset

Choose your settlement rail first (stripe_connect, stripe_ach_debit, stripe_mpp, adyen_manual_capture, or x402_usdc_base on settlementRail), then pick a matching completion preset for tool-completion evidence. Funding webhooks and /fund authorization move the intent to funded; presets describe what to submit after you hold a capability_token — never Stripe PaymentIntent ids or x402 payment-session ids as evidence.

# After rail choice — scaffold aligned evidence helpers
paybond init completion --preset ach_paid_api_ok          # stripe_ach_debit
paybond init completion --preset ach_travel_booking       # travel on ACH
paybond init completion --preset x402_travel_booking        # travel on x402
paybond init completion --preset x402_saas_api_purchase   # SaaS seat/API on x402
paybond init completion --preset x402_delivery_receipt      # x402 signed receipt
paybond init completion --preset invoice_payment_confirmed  # AP/invoice webhook (any rail)

See Funding vs completion for the full rail table and checklists.

Stablecoin funding via /fund

For intents created on the x402_usdc_base rail, Harbor returns a funding object with the payment-session metadata and the tenant-scoped harbor_fund_endpoint. Use paybond.intents.fundWithX402 for the full handshake (402 challenge → sign → retry → poll until capabilityToken).

const funded = await paybond.intents.fundWithX402({
  intentId,
  recognitionProof: await issueAgentRecognitionProofV1({
    purpose: "harbor.intent.fund",
    method: "POST",
    path: `/harbor/intents/${intentId}/fund`,
    body: {},
  }),
  signPayment: (challenge) => x402Wallet.signPayment(challenge),
  issueRecognitionProof: (envelope) =>
    issueAgentRecognitionProofV1({
      purpose: "harbor.intent.fund",
      method: envelope.method,
      path: envelope.path,
      body: envelope.body,
    }),
});
console.log(funded.statusCode, funded.funded, funded.capabilityToken);

signPayment and issueRecognitionProof stay app-owned — Kit never holds x402 wallet keys. Each /fund call needs a fresh AgentRecognitionProofV1 (single-use nonces).

Local x402 contract testing

ModeCommandWhat it exercises
Offline (no Docker)paybond dev loop --offlineIn-process Gateway mock with x402 fund state machine on POST /harbor/intents/{id}/fund
WireMock (Docker)paybond dev up then --gateway http://127.0.0.1:18089Scenario mappings 11–13: 402 → 202 → 200 for intent aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa

Point Paybond.open({ gateway: ... }) or paybond --gateway ... intents fund ... at the mock Gateway to rehearse fundWithX402 without a remote sandbox API.

MPP funding via /fund

For intents created on the stripe_mpp rail, Harbor returns WWW-Authenticate: Payment … challenges on 402. Use the helper that matches your funding mode:

ModeHelperChallenge
One-shot Stripe chargepaybond.intents.fundWithMppChargeintent="charge", method="stripe"
Tempo session channelpaybond.intents.fundWithMppSessionintent="session", method="tempo"
const funded = await paybond.intents.fundWithMppCharge({
  intentId,
  recognitionProof: await issueAgentRecognitionProofV1({
    purpose: "harbor.intent.fund",
    method: "POST",
    path: `/harbor/intents/${intentId}/fund`,
    body: {},
  }),
  createPaymentCredential: (challenge) => mppWallet.createPaymentCredential(challenge),
  issueRecognitionProof: (envelope) =>
    issueAgentRecognitionProofV1({
      purpose: "harbor.intent.fund",
      method: envelope.method,
      path: envelope.path,
      body: envelope.body,
    }),
});
console.log(funded.statusCode, funded.funded, funded.capabilityToken);
// funded.funding?.settlementAsset, depositAmountBaseUnits (create bootstrap)
// funded.funding?.intent, method, challengeId (after 402 challenge)
// funded.funding?.channelId, sessionProtocol, channelStatus (session mode)

createPaymentCredential and issueRecognitionProof stay app-owned — Kit never holds MPP wallet or SPT secrets. Kit retries with paymentAuthorization, sent as x-paybond-payment-authorization: Payment … so tenant Authorization: Bearer stays available.

For streaming session budgets, swap in fundWithMppSession when the intent needs a Tempo channel deposit instead of a one-shot charge.

Sandbox note: When Tempo session funding is configured in sandbox, the first fundWithMppCharge call may receive both charge and session WWW-Authenticate headers. The charge helper selects the intent="charge" challenge automatically; use fundWithMppSession when you intend to open a Tempo channel.

Advanced: manual /fund loop

Use paybond.intents.fund directly when you need fine-grained control over each HTTP status or idempotency key.

The snippet below uses two app-owned helpers: issueAgentRecognitionProofV1(...) creates a fresh request-bound proof, and x402Wallet.signPayment(...) signs the x402 challenge returned by Harbor.

const fundRecognitionProof = await issueAgentRecognitionProofV1({
  purpose: "harbor.intent.fund",
  method: "POST",
  path: `/harbor/intents/${intentId}/fund`,
  body: {},
});
const first = await paybond.intents.fund({ intentId, recognitionProof: fundRecognitionProof });
if (first.statusCode === 402) {
  const paymentRequired = first.paymentRequired;
  if (!paymentRequired) {
    throw new Error("missing PAYMENT-REQUIRED challenge");
  }

  const paymentSignature = await x402Wallet.signPayment(paymentRequired);
  const retryRecognitionProof = await issueAgentRecognitionProofV1({
    purpose: "harbor.intent.fund",
    method: "POST",
    path: `/harbor/intents/${intentId}/fund`,
    body: {},
  });

  const funded = await paybond.intents.fund({
    intentId,
    recognitionProof: retryRecognitionProof,
    paymentSignature,
  });
  if (!funded.capabilityToken) {
    throw new Error("funding is pending; poll /fund with a fresh recognition proof before guarding tools");
  }
  console.log(funded.statusCode, funded.funded, funded.capabilityToken);
} else if (first.capabilityToken) {
  console.log(first.statusCode, first.funded, first.capabilityToken);
} else {
  throw new Error("intent is not funded yet; poll /fund with a fresh recognition proof before guarding tools");
}

Notes (manual loop):

  • issueAgentRecognitionProofV1(...) is your trusted backend or agent-runner signer, not a Kit helper. Local sandbox/live quick-start scripts may load APP_FUND_RECOGNITION_PROOF_JSON and APP_FUND_RETRY_RECOGNITION_PROOF_JSON from the environment, but production code should issue a fresh AgentRecognitionProofV1 for each /fund call.
  • Generate the AgentRecognitionProofV1 with purpose: "harbor.intent.fund", verifier_context.tenant_id: paybond.harbor.tenantId, verifier_context.verifier_id: "paybond-gateway", and a request_envelope for POST /harbor/intents/{intentId}/fund whose body digest is the SHA-256 of the exact JSON body Kit sends ({} for this helper).
  • Use a unique nonce, short issued_at/expires_at window, and the Ed25519 private key for a tenant-registered agent key_id; the signed proof includes message_digest_sha256_hex, signing_public_key_ed25519_hex, and ed25519_signature_hex.
  • The retry needs its own recognition proof because proof nonces are single-use. paymentSignature is separate: it comes from your x402 wallet or facilitator after signing paymentRequired, and Kit sends it as the payment-signature header. If a local quick-start script uses APP_X402_PAYMENT_SIGNATURE, treat it as a stand-in for that signer output.
  • paybond.intents.fund calls Gateway POST /harbor/intents/{id}/fund.
  • 402 is a normal funding challenge, not an exception. The helper returns paymentRequired so your integration can call an x402-capable signer.
  • 202 means authorization is pending; poll /fund with a fresh recognition proof before guarding tools. 200 means Harbor transitioned the intent to funded.

Advanced troubleshooting

Only use direct token verification when support asks you to inspect an existing funded intent. Keep this out of production app configuration; normal integrations should read the capability token from create or fund.

export PAYBOND_INTENT_ID="00000000-0000-0000-0000-000000000000"
export PAYBOND_CAPABILITY="paybond_cap_..."
const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

try {
  const verified = await paybond.harbor.verifyCapability({
    intentId: process.env.PAYBOND_INTENT_ID!,
    token: process.env.PAYBOND_CAPABILITY!,
    operation: "travel.booker.purchase",
    requestedSpendCents: 18_700,
  });
  console.log(verified.allow, verified.code, verified.message);
} finally {
  await paybond.aclose();
}

Settlement confirmation

After evidence is submitted and the predicate passes, confirm settlement in-process:

await paybond.intents.confirmSettlement({
  intentId,
  recognitionProof,
  body: {}, // Harbor derives release/refund from the recorded predicate result.
});

For protocol/A2A automation use paybond.protocol.confirmHarborSettlement; for human-reviewed or disputed settlement use the Operator Console. See the Harbor API reference.

Error handling

Kit symbolRaised whenNotes
GatewayAuthErrorGateway rejected the API key or omitted tenant_id.statusCode and redacted bodyText on the instance.
HarborHttpErrorAny Harbor 4xx/5xx after retries are exhausted.Log statusCode, url, and a redacted bodyText; never log the API key, JWT, or capability token.
Plain Error (tenant / intent mismatch)Harbor echoed a different tenant or intent than requested on verify or ledger reads.Treat as a critical tenant-isolation error; do not retry.

See the Error handling guide for retry/backoff guidance and logging hygiene.

Further reading