@apifuse/provider-sdk 2.2.0-beta.40 → 2.2.0-beta.42

package/src/server/serve-implementation.ts

@@ -7,6 +7,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import { validateFailClosedDeclaration } from "../declaration-validation.js";
+import { safeProviderErrorObservability } from "../error-observability.js";
 import {
 	SDK_OWNED_PROVIDER_ERROR_CODES,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
@@ -19,7 +20,13 @@ import {
 	isTransportError,
 	isValidationError,
 	ProviderError,
+	type ProviderErrorObservability,
+	type ProviderErrorOptions,
 } from "../errors.js";
+import {
+	REDACTED_FIXTURE_VALUE,
+	sanitizeDiagnosticText,
+} from "../fixture-sanitization.js";
 import {
 	loadProviderLocaleCatalogs,
 	localizeAuthTurn,
@@ -140,7 +147,36 @@ export type ErrorObservabilityDetails = {
 	taxonomyVersion: string;
 	retryable: boolean;
 	upstreamStatus?: number;
+	providerObservability?: ProviderErrorObservability;
 };
+
+// Provider errors normally expose `options` through an own data property, but
+// providers can replace that property with a throwing accessor. Provider-controlled
+// accessor failures are absorbed into canonical classification rather than
+// propagated. By contract, read `options` directly instead of the public
+// `fix`/`details` convenience getters; provider-controlled accessors are not trusted.
+function providerErrorOption<K extends keyof ProviderErrorOptions>(
+	error: unknown,
+	key: K,
+): ProviderErrorOptions[K] | undefined {
+	if (!isProviderError(error)) return undefined;
+	try {
+		return (error as ProviderError).options?.[key] as ProviderErrorOptions[K] | undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function providerErrorCode(error: unknown): string | undefined {
+	if (!isProviderError(error)) return undefined;
+	try {
+		const code: unknown = (error as ProviderError).code;
+		return typeof code === "string" ? code : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"] as const;
 const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -989,6 +1025,8 @@ export type ProviderServerLogEvent =
 			errorCategory?: ProviderErrorCategory;
 			taxonomyVersion?: string;
 			retryable?: boolean;
+			providerObservability?: ProviderErrorObservability;
+			causeChain?: ProviderErrorCauseFrame[];
 			signal?: "unregistered_provider_error_code";
 			signalFix?: string;
 			issues?: Array<{ path: string; code: string; message: string }>;
@@ -1135,8 +1173,9 @@ function zodDetails(error: z.ZodError): Array<{
 function publicErrorSource(error: unknown, category: ProviderErrorCategory): ProviderErrorSource {
 	if (error instanceof StatefulRoutingDeadlineError) return "apifuse";
 	if (isProviderError(error)) {
-		if (error.code === MISSING_SECRET_CODE) return "apifuse";
-		if (error.code === "UPSTREAM_ERROR" || error.code === "BLOCKED") {
+		const code = providerErrorCode(error);
+		if (code === MISSING_SECRET_CODE) return "apifuse";
+		if (code === "UPSTREAM_ERROR" || code === "BLOCKED") {
 			return "upstream_failure";
 		}
 	}
@@ -1145,10 +1184,10 @@ function publicErrorSource(error: unknown, category: ProviderErrorCategory): Pro
 
 function toErrorResponse(
 	error: unknown,
-	requestId?: string,
-	declaredErrorCode?: OperationErrorCode,
+	requestId: string | undefined,
+	observabilityDetails: ErrorObservabilityDetails,
 ): OperationErrorResponse {
-	const observability = errorObservabilityDetails(error, declaredErrorCode);
+	const observability = observabilityDetails;
 	const source = publicErrorSource(error, observability.category);
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return {
@@ -1163,15 +1202,15 @@ function toErrorResponse(
 	}
 
 	if (isProviderError(error)) {
-		const details = error.details;
+		const details = providerErrorOption(error, "details");
 		return {
 			error: {
-				code: error.code ?? "provider_error",
+				code: providerErrorCode(error) ?? "provider_error",
 				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
 				retryable: observability.retryable,
 				source,
-				...(error.fix ? { fix: error.fix } : {}),
+				...(providerErrorOption(error, "fix") ? { fix: providerErrorOption(error, "fix") } : {}),
 				...(details !== undefined ? { details } : {}),
 			},
 		};
@@ -1231,9 +1270,9 @@ function providerObservabilityDetails(
 	// signal for exactly the retryOnAuthRefresh operations it is meant to enable.
 	if (isSessionExpiredError(error)) {
 		return {
-			category: error.options?.category ?? "credential_expired",
+			category: providerErrorOption(error, "category") ?? "credential_expired",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? declaredRetryable ?? false,
+			retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
 		};
 	}
 	// Missing-secret errors carry the canonical credential_unavailable category
@@ -1241,29 +1280,29 @@ function providerObservabilityDetails(
 	// the upstream. Matched by code (not constructor) so both the SDK-owned
 	// runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
 	// serialize identically, including across duplicate SDK module instances.
-	if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+	if (isProviderError(error) && providerErrorCode(error) === MISSING_SECRET_CODE) {
 		return {
-			category: error.options?.category ?? "credential_unavailable",
+			category: providerErrorOption(error, "category") ?? "credential_unavailable",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? declaredRetryable ?? false,
+			retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
 		};
 	}
 	if (!isTransportError(error)) {
 		return undefined;
 	}
 	const isProxyPoolCode =
-		error.code === PROXY_POOL_EXHAUSTED_CODE ||
-		error.code === PROXY_EDGE_AUTH_REJECTED_CODE ||
-		error.code === "PROXY_ALLOCATION_FAILED";
+		providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE ||
+		providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE ||
+		providerErrorCode(error) === "PROXY_ALLOCATION_FAILED";
 	const category =
-		error.options?.category ??
+		providerErrorOption(error, "category") ??
 		(isProxyPoolCode
 			? "proxy_pool"
-			: error.code === PROXY_AUTH_IP_DENIED_CODE
+			: providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE
 				? "anti_bot_blocked"
-				: error.code === "transport_timeout"
+				: providerErrorCode(error) === "transport_timeout"
 					? "timeout"
-					: error.code === "transport_network_error"
+					: providerErrorCode(error) === "transport_network_error"
 						? "network"
 						: error.upstreamStatus
 							? categoryForStatus(error.upstreamStatus)
@@ -1272,7 +1311,7 @@ function providerObservabilityDetails(
 		category,
 		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 		retryable:
-			error.options?.retryable ??
+			providerErrorOption(error, "retryable") ??
 			(category === "upstream_http" && error.upstreamStatus
 				? error.upstreamStatus >= 500
 				: isRetryableCategory(category)),
@@ -1280,7 +1319,7 @@ function providerObservabilityDetails(
 	};
 }
 
-function errorObservabilityDetails(
+function classifiedErrorObservabilityDetails(
 	error: unknown,
 	declaredErrorCode?: OperationErrorCode,
 ): ErrorObservabilityDetails {
@@ -1290,19 +1329,19 @@ function errorObservabilityDetails(
 
 	if (error instanceof z.ZodError || isValidationError(error)) {
 		const declaredStatus = effectiveDeclaration?.status;
+		const providerCategory = providerErrorOption(error, "category");
 		return {
-			category:
-				isProviderError(error) && error.options?.category
-					? error.options.category
-					: isEmittableErrorStatus(declaredStatus) &&
-							categoryForStatus(declaredStatus) === "upstream_rejected"
-						? "upstream_rejected"
-						: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
-							? "provider_error"
-							: "input_validation",
+			category: providerCategory
+				? providerCategory
+				: isEmittableErrorStatus(declaredStatus) &&
+						categoryForStatus(declaredStatus) === "upstream_rejected"
+					? "upstream_rejected"
+					: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+						? "provider_error"
+						: "input_validation",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: isProviderError(error)
-				? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+				? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
 				: false,
 		};
 	}
@@ -1322,15 +1361,16 @@ function errorObservabilityDetails(
 		// author set an explicit category.
 		const declaredStatus = effectiveDeclaration?.status;
 		const rejectionDefault =
-			error.code === "UPSTREAM_REJECTED" ||
+			providerErrorCode(error) === "UPSTREAM_REJECTED" ||
 			(isEmittableErrorStatus(declaredStatus) &&
 				categoryForStatus(declaredStatus) === "upstream_rejected")
 				? ("upstream_rejected" as const)
 				: ("provider_error" as const);
 		return {
-			category: error.options?.category ?? rejectionDefault,
+			category: providerErrorOption(error, "category") ?? rejectionDefault,
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
+			retryable:
+				providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
 		};
 	}
 
@@ -1341,16 +1381,24 @@ function errorObservabilityDetails(
 	};
 }
 
-function responseWithErrorObservability(
-	response: Response,
+function errorObservabilityDetails(
 	error: unknown,
 	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails {
+	const details = classifiedErrorObservabilityDetails(error, declaredErrorCode);
+	const providerObservability = safeProviderErrorObservability(error);
+	return {
+		...details,
+		...(providerObservability ? { providerObservability } : {}),
+	};
+}
+
+function responseWithErrorObservability(
+	response: Response,
+	observabilityDetails: ErrorObservabilityDetails,
 ): Response {
 	const headers = new Headers(response.headers);
-	headers.set(
-		ERROR_OBSERVABILITY_HEADER,
-		JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)),
-	);
+	headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(observabilityDetails));
 	return new Response(response.body, {
 		status: response.status,
 		statusText: response.statusText,
@@ -1360,18 +1408,18 @@ function responseWithErrorObservability(
 
 function publicProviderErrorMessage(error: ProviderError): string {
 	if (isTransportError(error)) {
-		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
+		if (providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE) {
 			return error.message;
 		}
-		if (error.code === PROXY_EDGE_AUTH_REJECTED_CODE) {
+		if (providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE) {
 			return error.message;
 		}
-		if (error.code === PROXY_POOL_EXHAUSTED_CODE) {
+		if (providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE) {
 			return error.message;
 		}
-		if (error.code === "transport_timeout") return "Request timed out";
-		if (error.code === "transport_network_error") return "Network error";
-		if (error.code === "upstream_http_error" && error.status) {
+		if (providerErrorCode(error) === "transport_timeout") return "Request timed out";
+		if (providerErrorCode(error) === "transport_network_error") return "Network error";
+		if (providerErrorCode(error) === "upstream_http_error" && error.status) {
 			return `Upstream request failed with status ${error.status}`;
 		}
 		if (error.status) {
@@ -1401,17 +1449,18 @@ function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): P
 		}
 		// Canonical SDK code → status mapping lives in error-resolution.ts so
 		// the authoring lint and this runtime path share one source of truth.
-		if (typeof error.code === "string") {
-			const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+		const code = providerErrorCode(error);
+		if (typeof code === "string") {
+			const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(code);
 			if (mappedStatus !== undefined) {
 				return mappedStatus;
 			}
 		}
 		if (isTransportError(error)) {
-			return error.code === "transport_timeout" ? 504 : 502;
+			return providerErrorCode(error) === "transport_timeout" ? 504 : 502;
 		}
 		if (isValidationError(error)) {
-			return error.options?.category === "output_validation" ? 500 : 400;
+			return providerErrorOption(error, "category") === "output_validation" ? 500 : 400;
 		}
 
 		return 500;
@@ -1425,11 +1474,9 @@ function sdkOwnsErrorResolution(error: unknown): boolean {
 	if (isTransportError(error)) return true;
 	if (error instanceof z.ZodError) return true;
 	if (error instanceof StatefulRoutingDeadlineError) return true;
-	return (
-		isProviderError(error) &&
-		typeof error.code === "string" &&
-		SDK_RUNTIME_OWNED_ERROR_CODES.has(error.code)
-	);
+	if (!isProviderError(error)) return false;
+	const code = providerErrorCode(error);
+	return typeof code === "string" && SDK_RUNTIME_OWNED_ERROR_CODES.has(code);
 }
 
 type OperationErrorCodeLookup = ReadonlyMap<string, ReadonlyMap<string, OperationErrorCode>>;
@@ -1450,8 +1497,9 @@ function declaredErrorCodeFor(
 	operationId: string | undefined,
 	lookup: OperationErrorCodeLookup,
 ): OperationErrorCode | undefined {
-	if (!operationId || !isProviderError(error) || typeof error.code !== "string") return undefined;
-	return lookup.get(operationId)?.get(error.code);
+	const code = providerErrorCode(error);
+	if (!operationId || !code) return undefined;
+	return lookup.get(operationId)?.get(code);
 }
 
 function extractRequestId(raw: unknown): string | undefined {
@@ -1463,14 +1511,63 @@ function extractRequestId(raw: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
 
-type ProviderErrorCauseFrame = {
+export type ProviderErrorCauseFrame = {
 	errorClass: string;
 	code?: string;
+	message: string;
 	messageLength: number;
 	messageFingerprint: string;
+	providerObservability?: ProviderErrorObservability;
 };
 
 const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+const MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH = 300;
+const UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE = "[UNSTRUCTURED_UPSTREAM_TEXT]";
+const PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN = /https?:\/\/[^\s"'<>]+/giu;
+const PROVIDER_ERROR_CAUSE_TOKEN_RUN = /\S+/gu;
+const PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION =
+	/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
+const STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS = new Set([
+	"completion",
+	"diagnostic",
+	"provider",
+	"rejected",
+	"returned",
+	"upstream",
+]);
+
+/**
+ * Cause frames fail closed when sanitization leaves a plausible credential-shaped free-text run.
+ * Redaction sentinels and retained URLs are ignored. Every other whitespace token (or each side
+ * of a structured key=value token) with at least eight Unicode characters must reduce to this
+ * small vocabulary drawn from SDK diagnostics; counting punctuation keeps bare passwords opaque.
+ */
+function isStructurallySafeProviderErrorCauseMessage(message: string): boolean {
+	const classifiableMessage = message
+		.replaceAll(REDACTED_FIXTURE_VALUE, " ")
+		.replace(PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN, " ");
+	for (const match of classifiableMessage.matchAll(PROVIDER_ERROR_CAUSE_TOKEN_RUN)) {
+		const token = match[0];
+		for (const run of token.split("=")) {
+			const diagnosticWord = run
+				.replace(PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION, "")
+				.toLowerCase();
+			if (STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS.has(diagnosticWord)) continue;
+			if ([...run].length >= 8) return false;
+		}
+	}
+	return true;
+}
+
+function providerErrorCauseMessage(message: string): string {
+	const sanitized = sanitizeDiagnosticText(message);
+	if (!isStructurallySafeProviderErrorCauseMessage(sanitized)) {
+		return UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE;
+	}
+	return sanitized.length > MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH
+		? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH)}… [truncated]`
+		: sanitized;
+}
 
 function providerErrorCauseChain(error: unknown): ProviderErrorCauseFrame[] | undefined {
 	if (!(error instanceof Error) && !isProviderError(error)) return undefined;
@@ -1486,11 +1583,15 @@ function providerErrorCauseChain(error: unknown): ProviderErrorCauseFrame[] | un
 	) {
 		seen.add(cause);
 		const message = cause.message;
+		const providerObservability = safeProviderErrorObservability(cause);
+		const causeCode = providerErrorCode(cause);
 		frames.push({
 			errorClass: cause.name,
-			...(isProviderError(cause) && typeof cause.code === "string" ? { code: cause.code } : {}),
+			...(causeCode !== undefined ? { code: causeCode } : {}),
+			message: providerErrorCauseMessage(message),
 			messageLength: message.length,
 			messageFingerprint: createHash("sha256").update(message).digest("hex").slice(0, 12),
+			...(providerObservability ? { providerObservability } : {}),
 		});
 		cause = cause.cause;
 	}
@@ -1507,11 +1608,13 @@ function logProviderError(
 	error: unknown,
 	status: number,
 	cost: ProviderRequestCost,
-	declaredErrorCode?: OperationErrorCode,
-	proxyTelemetry?: ProxyTelemetryCollector,
+	declaredErrorCode: OperationErrorCode | undefined,
+	proxyTelemetry: ProxyTelemetryCollector | undefined,
+	observabilityDetails: ErrorObservabilityDetails,
 ): void {
+	const providerCode = isProviderError(error) ? providerErrorCode(error) : undefined;
 	const code = isProviderError(error)
-		? (error.code ?? "provider_error")
+		? (providerCode ?? "provider_error")
 		: error instanceof z.ZodError
 			? "invalid_request"
 			: error instanceof StatefulRoutingDeadlineError
@@ -1520,16 +1623,22 @@ function logProviderError(
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
 	const causeChain = providerErrorCauseChain(error);
-	const details = errorObservabilityDetails(error, declaredErrorCode);
+	const details = observabilityDetails;
 	const isUnregisteredProviderErrorCode =
 		status === 500 &&
 		isProviderError(error) &&
 		!isValidationError(error) &&
-		typeof error.code === "string" &&
-		!SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+		typeof providerCode === "string" &&
+		!SDK_OWNED_PROVIDER_ERROR_CODES.has(providerCode) &&
 		declaredErrorCode === undefined;
 	const proxy = proxyTelemetry?.toLogPayload();
 	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
+	// The logger is caller-supplied and may mutate the event synchronously.
+	// Give it an independent snapshot so those mutations cannot corrupt the
+	// observability header serialized immediately afterwards.
+	const providerObservability = details.providerObservability
+		? { ...details.providerObservability }
+		: undefined;
 	emit({
 		level: status >= 500 ? "error" : "warn",
 		event: "provider_request_failed",
@@ -1544,6 +1653,7 @@ function logProviderError(
 		errorClass,
 		message,
 		...(causeChain ? { causeChain } : {}),
+		...(providerObservability ? { providerObservability } : {}),
 		...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
 		errorCategory: details.category,
 		taxonomyVersion: details.taxonomyVersion,
@@ -2375,7 +2485,11 @@ function createServerAppWithCapabilityModules(
 
 	app.notFound((c) => {
 		const error = new ProviderError("Not found", { code: "not_found", retryable: false });
-		return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+		const observabilityDetails = errorObservabilityDetails(error);
+		return responseWithErrorObservability(
+			c.json(toErrorResponse(error, undefined, observabilityDetails), 404),
+			observabilityDetails,
+		);
 	});
 
 	app.get("/health", (c) =>
@@ -2534,10 +2648,14 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
 			const status = toStatusCode(error, declaredErrorCode);
-			if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
+			if (
+				isProviderError(error) &&
+				providerErrorCode(error) === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL"
+			) {
 				c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
 			}
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
 			logProviderError(
 				logger,
 				provider,
@@ -2548,11 +2666,12 @@ function createServerAppWithCapabilityModules(
 				status,
 				finishRequestCost(requestCost),
 				declaredErrorCode,
+				undefined,
+				observabilityDetails,
 			);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId, declaredErrorCode), status),
-				error,
-				declaredErrorCode,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2609,6 +2728,7 @@ function createServerAppWithCapabilityModules(
 			const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
 			const status = toStatusCode(error, declaredErrorCode);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
 			logProviderError(
 				logger,
 				provider,
@@ -2620,13 +2740,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				declaredErrorCode,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId, declaredErrorCode), status),
-				error,
-				declaredErrorCode,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2668,6 +2788,7 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error);
 			logProviderError(
 				logger,
 				provider,
@@ -2679,12 +2800,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				undefined,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
-				error,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2726,6 +2848,7 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error);
 			logProviderError(
 				logger,
 				provider,
@@ -2737,12 +2860,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				undefined,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
-				error,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2784,6 +2908,7 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error);
 			logProviderError(
 				logger,
 				provider,
@@ -2795,12 +2920,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				undefined,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
-				error,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2842,6 +2968,7 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error);
 			logProviderError(
 				logger,
 				provider,
@@ -2853,12 +2980,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				undefined,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
-				error,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});
@@ -2900,6 +3028,7 @@ function createServerAppWithCapabilityModules(
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
+			const observabilityDetails = errorObservabilityDetails(error);
 			logProviderError(
 				logger,
 				provider,
@@ -2911,12 +3040,13 @@ function createServerAppWithCapabilityModules(
 				finishRequestCost(requestCost),
 				undefined,
 				proxyTelemetry,
+				observabilityDetails,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
-				error,
+				c.json(toErrorResponse(error, requestId, observabilityDetails), status),
+				observabilityDetails,
 			);
 		}
 	});