Privacy And Redaction

An original exception is useful to operators but is not automatically safe. Provider SDKs and infrastructure libraries may include prompts, request fragments, URLs, identifiers, or credentials in messages and attached fields.

Data Boundaries

PAI does not attach bodies, headers, prompts, complete identity or scope objects, client data, tool inputs, or tool outputs to diagnostic events automatically.

Map Only Deliberately Safe Details

Use an allowlist in runtime mapError and receiver mapHttpError. A shared pure function can serve both boundaries:

import type { PaiErrorDetails } from "@pai/protocol";

function mapError(error: unknown): PaiErrorDetails | undefined {
  if (error instanceof UnsupportedDocumentError) {
    return {
      code: "unsupported_document",
      message: "This document cannot be processed.",
      retryable: false,
    };
  }

  return undefined;
}

Returning undefined uses PAI's built-in mapping or generic safe fallback. Never copy an arbitrary error.message into the public mapping merely because it is convenient.

PAI isolates a mapper that throws or returns invalid details. PAI then uses any built-in safe mapping or the generic safe fallback, while the original application failure remains available at the trusted diagnostic boundary.

Redact Trusted Logs

For environments that cannot retain raw messages or stacks, replace the default reporter with an allowlist:

function approvedErrorFields(error: unknown) {
  if (!(error instanceof Error)) return { type: typeof error };

  const candidate = error as Error & { code?: unknown };
  return {
    name: candidate.name,
    code: typeof candidate.code === "string" ? candidate.code : undefined,
  };
}

createPaiHonoReceiver({
  pai,
  resolveIdentity,
  onHttpError(event) {
    logger.error(
      {
        errorId: event.errorId,
        operation: event.operation,
        phase: event.phase,
        error: approvedErrorFields(event.error),
      },
      "PAI HTTP failure",
    );
  },
});

Pattern-based removal of known secret formats is not a complete compliance strategy. Prefer selecting approved fields.

Passing onHttpError: false or onRuntimeError: false suppresses that boundary's default reporter. Only do this when another trusted diagnostic path satisfies your support and retention requirements; a client reference is useful only when a backend sink records the matching event. PAI omits the reference when reporting is deliberately suppressed.

Telemetry

Run inputs and outputs, model outputs, tool inputs and outputs, tool data, and original exception details remain disabled by default. Enable original error details only for an approved telemetry sink:

createPaiOpenTelemetry({
  serviceName: "assistant-api",
  contentCapture: {
    recordErrorDetails: true,
  },
});

The object form keeps error details independent from the other payload controls. The contentCapture: true shorthand intentionally enables every PAI-owned content field, including raw errors, run/model payloads, and tool payloads.

Telemetry integrations are observational. A failed exporter, processor, context operation, or span method can remove diagnostics but cannot fail or repeat application work.

See Observability for telemetry configuration.

Retention And Identifiers

Treat errorId, thread id, run id, runtime instance id, agent version, and application telemetry attributes according to your own identifier and retention policy. They are designed for correlation, not authentication.

PAI does not expose a public error lookup endpoint. Keep access to original exceptions inside the authorization boundary of your logging or error reporting system.