@apifuse/provider-sdk 2.2.0-beta.13 → 2.2.0-beta.14

package/AUTHORING.md

@@ -393,6 +393,70 @@ External contributors are expected to submit standalone Provider source plus:
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Error responses
+
+Provider-server failures use a stable public envelope:
+
+```json
+{
+  "error": {
+    "code": "UPSTREAM_ERROR",
+    "message": "The upstream service failed",
+    "requestId": "req_123",
+    "retryable": true,
+    "details": { "providerReason": "temporarily_unavailable" }
+  }
+}
+```
+
+`retryable` is always present on responses emitted by the current SDK. Set
+`retryable` in the `ProviderError` options when the provider knows the answer;
+an explicit `true` or `false` wins over SDK derivation. When it is omitted, the
+SDK derives the value for its known error classes and otherwise defaults to
+`false`. During stateful rolling upgrades, the forwarding client also accepts
+an older owner response that omits `retryable` and treats it as `false` without
+loosening the emitted response contract. Existing optional `fix` guidance is
+also preserved when a `ProviderError` supplies it.
+
+`details` belongs exclusively to the provider. The server passes
+`ProviderError.options.details` through verbatim, including strings and arrays,
+and never merges, overwrites, or wraps it. Do not put SDK taxonomy fields there.
+SDK-owned validation and masked-internal-error paths retain their own diagnostic
+details.
+
+SDK observability is emitted separately in the
+`X-ApiFuse-Error-Observability` response header as compact, single-line JSON:
+
+```json
+{"category":"upstream_http","taxonomyVersion":"2026-05-26","retryable":true,"upstreamStatus":502}
+```
+
+Treat this header as telemetry, not as provider-controlled public error detail.
+Its category, taxonomy version, retryability, and optional upstream status match
+the structured `provider_request_failed` log event.
+
+Registered error-code mappings take precedence for every `ProviderError`,
+including `ValidationError`:
+
+| Error code or fallback | HTTP status |
+| --- | ---: |
+| `AUTH_REQUIRED`, `reauth_required` | 401 |
+| `MISSING_SECRET` | 400 |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | 404 |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 429 |
+| `UPSTREAM_ERROR`, `BLOCKED` | 502 |
+| `STT_UNAVAILABLE`, `UNSUPPORTED_STT_BACKEND`, `STATEFUL_FORWARDING_REPLAY_CACHE_FULL` | 503 |
+| Unregistered input `ValidationError` code | 400 |
+| Other unregistered `ProviderError` code | 500 |
+
+An unregistered non-validation `ProviderError` code returns HTTP 500 and emits
+the greppable `unregistered_provider_error_code` signal with the code in the
+structured failure log. Before publishing a new code, register its status in
+the SDK mapping and add it to the mapping tests; declaring it only in operation
+documentation does not change runtime status selection. The HTTP 400
+`ValidationError` behavior is only the fallback for unregistered input
+validation codes; a registered code such as `NOT_FOUND` retains its mapped 404.
+
 ### Declared secrets are SDK-enforced
 
 Environment/secret presence validation is single-sourced in the SDK. Declare
@@ -411,12 +475,12 @@ secrets: [
 The runtime validates every `required: true` declaration before any operation
 handler or auth-flow handler (except `abort`) runs. When a required secret is
 unset or whitespace-only, the invocation fails with the canonical structured
-error — code `MISSING_SECRET`, HTTP 400, `details.category:
-"credential_unavailable"`, `retryable: false`, and a `fix` naming every missing
-secret — across `/v1/{operation}`, self-test probes, `apifuse perf`, and
-`apifuse record`. The server also emits a `provider_secrets_missing` warn log
-at boot so unprovisioned deployments are visible immediately without crashing
-the pod.
+error — code `MISSING_SECRET`, HTTP 400, top-level `retryable: false`, and a
+`fix` naming every missing secret — across `/v1/{operation}`, self-test probes,
+`apifuse perf`, and `apifuse record`. Its error-observability header carries the
+`credential_unavailable` category. The server also emits a
+`provider_secrets_missing` warn log at boot so unprovisioned deployments are
+visible immediately without crashing the pod.
 
 Provider-local presence re-validation is **deprecated**: do not write
 `requireServiceKey`/`requireApiKey`-style guards that re-check `ctx.env.get()`

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.14
+
+- Release candidate for main commit 3491acd253ca17b517985e8a618f1c2904a664a9.
+
 ## 2.2.0-beta.13
 
 - Release candidate for main commit 75e840d0614aea3b99a1e5cef4f93f8cdccf0507.
@@ -82,6 +86,8 @@
 
 ## Unreleased
 
+- **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.
+- Unregistered `ProviderError` codes now default to HTTP 500 instead of 400 and emit an `unregistered_provider_error_code` structured-log signal; registered mappings remain unchanged and take precedence over the HTTP 400 fallback for unregistered input `ValidationError` codes.
 - Add an opt-in native connection idle read timeout with a typed error, independently from TCP/SOCKS/TLS establishment deadlines.
 - Add opt-in `maxBodyBytes` enforcement to stealth fetches and redirect hops, aborting oversized decoded response streams with `response_too_large`.
 - Resolve relative date tokens in fixture requests before input-schema validation, add KST capture-date `fixtures.recordedAt` metadata, and support explicit KST/UTC calendars in the shared health-input resolver.

package/dist/errors.d.ts

@@ -47,6 +47,7 @@ export declare class TransportError extends ProviderError {
 export declare function isProviderError(value: unknown): value is ProviderError;
 export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
 export declare function isTransportError(value: unknown): value is TransportError;
+export declare function isValidationError(value: unknown): value is ValidationError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }

package/dist/errors.js

@@ -8,6 +8,7 @@ const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
 const PROVIDER_ERROR_BRAND_VALUE = 1;
 const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
 const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+const VALIDATION_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/validation@1");
 // Defines a non-enumerable, non-writable, non-configurable own data property.
 // Immutable + own means a guard can trust it via a single descriptor read
 // without invoking attacker-controlled getters or accepting inherited brands.
@@ -96,6 +97,7 @@ export class ValidationError extends ProviderError {
         super(message, options);
         this.name = "ValidationError";
         this.zodError = options?.zodError;
+        defineErrorBrand(this, VALIDATION_BRAND, true);
     }
 }
 export class TransportError extends ProviderError {
@@ -122,6 +124,10 @@ export function isSessionExpiredError(value) {
 export function isTransportError(value) {
     return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
+export function isValidationError(value) {
+    return (isProviderError(value) &&
+        (hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError"));
+}
 export class ProviderSecretError extends ProviderError {
     constructor(message, options) {
         super(message, { code: "provider_secret_error", ...options });

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export { createServerApp, type ServeOptions, serve } from "./server/index.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";

package/dist/index.js

@@ -31,7 +31,7 @@ export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
-export { createServerApp, serve } from "./server/index.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";

package/dist/runtime/executor.js

@@ -1,4 +1,5 @@
-import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import { isSessionExpiredError, isValidationError, ProviderError, SessionExpiredError, ValidationError, } from "../errors.js";
+import { z } from "zod";
 import { parseSchema } from "../schema.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
@@ -59,5 +60,19 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (isStreamingOperation(provider, operationId)) {
         return result;
     }
-    return parseSchema(operation.output, result, `operations.${operationId}.output`);
+    try {
+        return await parseSchema(operation.output, result, `operations.${operationId}.output`);
+    }
+    catch (cause) {
+        if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+            throw cause;
+        }
+        throw new ValidationError(`Operation handler output failed schema validation.`, {
+            code: "OUTPUT_VALIDATION_FAILED",
+            category: "output_validation",
+            retryable: false,
+            zodError: isValidationError(cause) ? cause.zodError : cause,
+            ...(cause instanceof Error ? { cause } : {}),
+        });
+    }
 }

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { createServerApp, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";

package/dist/server/index.js

@@ -1,4 +1,4 @@
-export { createServerApp, serve, } from "./serve.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";

package/dist/server/serve.d.ts

@@ -3,6 +3,14 @@ import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
 import type { ProviderContext, ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
 import { type OperationRequest } from "./types.js";
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+    category: ProviderErrorCategory;
+    taxonomyVersion: string;
+    retryable: boolean;
+    upstreamStatus?: number;
+};
 export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
     requestId: z.ZodString;
     providerId: z.ZodString;
@@ -78,6 +86,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     errorCategory?: ProviderErrorCategory;
     taxonomyVersion?: string;
     retryable?: boolean;
+    signal?: "unregistered_provider_error_code";
     issues?: Array<{
         path: string;
         code: string;

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
-import { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, } from "../errors.js";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -33,6 +33,8 @@ import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -320,25 +322,27 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
+    const observability = errorObservabilityDetails(error);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
                 code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
                 message: "Stateful forwarding deadline expired.",
                 ...(requestId ? { requestId } : {}),
-                details: { retryable: false },
+                retryable: observability.retryable,
             },
         };
     }
     if (isProviderError(error)) {
-        const details = publicProviderErrorDetails(error);
+        const details = error.details;
         return {
             error: {
                 code: error.code ?? "provider_error",
                 message: publicProviderErrorMessage(error),
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 ...(error.fix ? { fix: error.fix } : {}),
-                ...(details ? { details } : {}),
+                ...(details !== undefined ? { details } : {}),
             },
         };
     }
@@ -348,6 +352,7 @@ function toErrorResponse(error, requestId) {
                 code: "invalid_request",
                 message: "Invalid request body",
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 details: zodDetails(error),
             },
         };
@@ -363,6 +368,7 @@ function toErrorResponse(error, requestId) {
             code: "internal_error",
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
+            retryable: observability.retryable,
             details: {
                 retryable: false,
                 category: "internal_error",
@@ -371,26 +377,6 @@ function toErrorResponse(error, requestId) {
         },
     };
 }
-function publicProviderErrorDetails(error) {
-    const providerDetails = error.details;
-    const observabilityDetails = providerObservabilityDetails(error);
-    if (providerDetails === undefined) {
-        return observabilityDetails;
-    }
-    if (observabilityDetails === undefined) {
-        return providerDetails;
-    }
-    if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
-        return { ...providerDetails, ...observabilityDetails };
-    }
-    return {
-        provider: providerDetails,
-        observability: observabilityDetails,
-    };
-}
-function isPlainRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 // Accepts `unknown` so the branded guards narrow cleanly from the top: the
 // subtype error classes are structurally compatible with ProviderError, so
 // narrowing from a ProviderError-typed value would collapse the negative branch
@@ -449,6 +435,48 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
+function errorObservabilityDetails(error) {
+    const providerDetails = providerObservabilityDetails(error);
+    if (providerDetails)
+        return providerDetails;
+    if (error instanceof z.ZodError || isValidationError(error)) {
+        return {
+            category: isProviderError(error) && error.options?.category
+                ? error.options.category
+                : "input_validation",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+        };
+    }
+    if (error instanceof StatefulRoutingDeadlineError) {
+        return {
+            category: "timeout",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: false,
+        };
+    }
+    if (isProviderError(error)) {
+        return {
+            category: error.options?.category ?? "provider_error",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: error.options?.retryable ?? false,
+        };
+    }
+    return {
+        category: "internal_error",
+        taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+        retryable: false,
+    };
+}
+function responseWithErrorObservability(response, error) {
+    const headers = new Headers(response.headers);
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
 function publicProviderErrorMessage(error) {
     if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
@@ -481,9 +509,6 @@ function toStatusCode(error) {
     if (error instanceof StatefulRoutingDeadlineError) {
         return 504;
     }
-    if (isTransportError(error)) {
-        return error.code === "transport_timeout" ? 504 : 502;
-    }
     if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
@@ -509,10 +534,87 @@ function toStatusCode(error) {
             case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
                 return 503;
         }
-        return 400;
+        if (isTransportError(error)) {
+            return error.code === "transport_timeout" ? 504 : 502;
+        }
+        if (isValidationError(error)) {
+            return error.options?.category === "output_validation" ? 500 : 400;
+        }
+        return 500;
     }
     return 500;
 }
+// Codes emitted by SDK-owned paths must never be attributed to provider
+// authors by the unregistered-code signal, even when their intentional status
+// is 500. Provider-authored codes not in this registry retain the signal.
+const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+    "AUTH_PROMPT_UNAVAILABLE",
+    "BROWSER_CDP_POOL_REQUIRED",
+    "BROWSER_RUNTIME_UNSUPPORTED",
+    "STEALTH_RUNTIME_UNSUPPORTED",
+    "SSE_EVENT_UNDECLARED",
+    "STREAM_EVENT_TOO_LARGE",
+    "STREAM_CHUNK_TOO_LARGE",
+    "SSE_RESULT_UNSUPPORTED",
+    "STREAM_RESULT_UNSUPPORTED",
+    "AUTH_FLOW_NOT_CONFIGURED",
+    "refresh_not_supported",
+    "RUNTIME_UNSUPPORTED",
+    "PROVIDER_STATE_UNSUPPORTED",
+    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+    "CHOICE_STATE_UNAVAILABLE",
+    "CHOICE_CONTEXT_REQUIRED",
+    "unsupported_stealth_cookie_store_version",
+    "provider_secret_error",
+    "credential_key_error",
+    "credential_mode_error",
+    "flow_expired",
+    "turn_validation_error",
+    "context_access_error",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "STT_AUDIO_TOO_LARGE",
+    "STT_UPSTREAM_FAILED",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "retry_invalid_policy",
+    "retry_unsafe_method",
+    "stealth_cookie_store_serialize_failed",
+    "response_too_large",
+    "transport_stream_unavailable",
+    "transport_invalid_method",
+    "http_transport_override_unsupported",
+    "transport_invalid_url",
+    "retry_exhausted",
+    "auth_abort_unsafe_data",
+    "credentials_auth_missing_credential_keys",
+    "credentials_auth_missing_credential",
+    "credentials_auth_invalid_login_result",
+    "credentials_auth_unknown_challenge",
+    "credentials_auth_unknown_pending_challenge",
+    "STATEFUL_FORWARDING_NOT_CONFIGURED",
+    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
+    "STATEFUL_FORWARDING_NONCE_INVALID",
+    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
+    "STATEFUL_FORWARDING_REPLAY_DETECTED",
+    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+    "STATEFUL_FORWARDING_REQUEST_FAILED",
+    "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_BAD_RESPONSE",
+    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -530,7 +632,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+    const details = errorObservabilityDetails(error);
+    const isUnregisteredProviderErrorCode = status === 500 &&
+        isProviderError(error) &&
+        !isValidationError(error) &&
+        typeof error.code === "string" &&
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -544,15 +651,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(isTransportError(error) && error.upstreamStatus
-            ? { upstreamStatus: error.upstreamStatus }
-            : {}),
-        ...(details
-            ? {
-                errorCategory: details.category,
-                taxonomyVersion: details.taxonomyVersion,
-                retryable: details.retryable,
-            }
+        ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+        errorCategory: details.category,
+        taxonomyVersion: details.taxonomyVersion,
+        retryable: details.retryable,
+        ...(isUnregisteredProviderErrorCode
+            ? { signal: "unregistered_provider_error_code" }
             : {}),
         ...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
     });
@@ -1150,12 +1254,10 @@ export function createServerApp(provider, options = {}) {
             missingSecrets: missingSecretsAtBoot,
         });
     }
-    app.notFound((c) => c.json({
-        error: {
-            code: "not_found",
-            message: "Not found",
-        },
-    }, 404));
+    app.notFound((c) => {
+        const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+        return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+    });
     app.get("/health", (c) => c.json({
         status: "ok",
         provider: provider.id,
@@ -1272,7 +1374,7 @@ export function createServerApp(provider, options = {}) {
             }
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1306,7 +1408,7 @@ export function createServerApp(provider, options = {}) {
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/start", async (c) => {
@@ -1326,7 +1428,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/continue", async (c) => {
@@ -1346,7 +1448,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/poll", async (c) => {
@@ -1366,7 +1468,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/refresh", async (c) => {
@@ -1386,7 +1488,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/disconnect", async (c) => {
@@ -1406,7 +1508,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     return app;

package/dist/server/types.d.ts

@@ -42,6 +42,7 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodBoolean;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -84,6 +85,7 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -121,6 +123,7 @@ export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -21,6 +21,7 @@ export const ErrorEnvelopeSchema = z.object({
     code: z.string(),
     message: z.string(),
     requestId: z.string().optional(),
+    retryable: z.boolean(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });

package/dist/stateful/stateful-provider-owner-forwarder.js

@@ -9,6 +9,14 @@ export const STATEFUL_FORWARDING_NONCE_HEADER = "x-apifuse-stateful-nonce";
 export const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
 const MAX_FORWARDED_HEADERS = 32;
 const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+    error: OperationErrorResponseSchema.shape.error.extend({
+        retryable: z.boolean().optional().default(false),
+    }),
+});
 const SENSITIVE_HEADER_NAMES = new Set([
     "authorization",
     "cookie",
@@ -183,7 +191,7 @@ async function parseForwardedResponse(response) {
     if (response.ok && success.success) {
         return { output: success.data.data };
     }
-    const error = OperationErrorResponseSchema.safeParse(body);
+    const error = ForwardedOperationErrorResponseSchema.safeParse(body);
     if (error.success) {
         throw new StatefulOwnerForwardingError({
             code: error.data.error.code,

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.13",
+	"version": "2.2.0-beta.14",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/errors.ts

@@ -10,6 +10,7 @@ const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
 const PROVIDER_ERROR_BRAND_VALUE = 1;
 const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
 const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+const VALIDATION_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/validation@1");
 
 // Defines a non-enumerable, non-writable, non-configurable own data property.
 // Immutable + own means a guard can trust it via a single descriptor read
@@ -125,6 +126,7 @@ export class ValidationError extends ProviderError {
 		super(message, options);
 		this.name = "ValidationError";
 		this.zodError = options?.zodError;
+		defineErrorBrand(this, VALIDATION_BRAND, true);
 	}
 }
 
@@ -162,6 +164,13 @@ export function isTransportError(value: unknown): value is TransportError {
 	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
 
+export function isValidationError(value: unknown): value is ValidationError {
+	return (
+		isProviderError(value) &&
+		(hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError")
+	);
+}
+
 export class ProviderSecretError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, { code: "provider_secret_error", ...options });

package/src/index.ts

@@ -135,7 +135,12 @@ export {
 	sensitive,
 	z,
 } from "./schema.js";
-export { createServerApp, type ServeOptions, serve } from "./server/index.js";
+export {
+	createServerApp,
+	ERROR_OBSERVABILITY_HEADER,
+	type ServeOptions,
+	serve,
+} from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export type {

package/src/runtime/executor.ts

@@ -1,4 +1,11 @@
-import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import {
+	isSessionExpiredError,
+	isValidationError,
+	ProviderError,
+	SessionExpiredError,
+	ValidationError,
+} from "../errors.js";
+import { z } from "zod";
 import { parseSchema } from "../schema.js";
 import type { ProviderContext, ProviderDefinition } from "../types.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
@@ -81,5 +88,18 @@ export async function executeOperation(
 		return result;
 	}
 
-	return parseSchema(operation.output, result, `operations.${operationId}.output`);
+	try {
+		return await parseSchema(operation.output, result, `operations.${operationId}.output`);
+	} catch (cause) {
+		if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+			throw cause;
+		}
+		throw new ValidationError(`Operation handler output failed schema validation.`, {
+			code: "OUTPUT_VALIDATION_FAILED",
+			category: "output_validation",
+			retryable: false,
+			zodError: isValidationError(cause) ? cause.zodError : cause,
+			...(cause instanceof Error ? { cause } : {}),
+		});
+	}
 }

package/src/server/index.ts

@@ -1,5 +1,7 @@
 export {
 	createServerApp,
+	ERROR_OBSERVABILITY_HEADER,
+	type ErrorObservabilityDetails,
 	type ProviderServerCloseOptions,
 	type ProviderServerHandle,
 	type ProviderServerLogEvent,

package/src/server/serve.ts

@@ -9,6 +9,7 @@ import {
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
+	isValidationError,
 	ProviderError,
 } from "../errors.js";
 import {
@@ -108,6 +109,14 @@ import {
 
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+	category: ProviderErrorCategory;
+	taxonomyVersion: string;
+	retryable: boolean;
+	upstreamStatus?: number;
+};
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"] as const;
 const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -486,6 +495,7 @@ export type ProviderServerLogEvent =
 			errorCategory?: ProviderErrorCategory;
 			taxonomyVersion?: string;
 			retryable?: boolean;
+			signal?: "unregistered_provider_error_code";
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
 	| {
@@ -604,26 +614,28 @@ function zodDetails(error: z.ZodError): Array<{
 }
 
 function toErrorResponse(error: unknown, requestId?: string): OperationErrorResponse {
+	const observability = errorObservabilityDetails(error);
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return {
 			error: {
 				code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
 				message: "Stateful forwarding deadline expired.",
 				...(requestId ? { requestId } : {}),
-				details: { retryable: false },
+				retryable: observability.retryable,
 			},
 		};
 	}
 
 	if (isProviderError(error)) {
-		const details = publicProviderErrorDetails(error);
+		const details = error.details;
 		return {
 			error: {
 				code: error.code ?? "provider_error",
 				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
 				...(error.fix ? { fix: error.fix } : {}),
-				...(details ? { details } : {}),
+				...(details !== undefined ? { details } : {}),
 			},
 		};
 	}
@@ -634,6 +646,7 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 				code: "invalid_request",
 				message: "Invalid request body",
 				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
 				details: zodDetails(error),
 			},
 		};
@@ -650,6 +663,7 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 			code: "internal_error",
 			message: "Internal error",
 			...(requestId ? { requestId } : {}),
+			retryable: observability.retryable,
 			details: {
 				retryable: false,
 				category: "internal_error",
@@ -659,42 +673,12 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 	};
 }
 
-function publicProviderErrorDetails(error: ProviderError): unknown {
-	const providerDetails = error.details;
-	const observabilityDetails = providerObservabilityDetails(error);
-
-	if (providerDetails === undefined) {
-		return observabilityDetails;
-	}
-	if (observabilityDetails === undefined) {
-		return providerDetails;
-	}
-	if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
-		return { ...providerDetails, ...observabilityDetails };
-	}
-	return {
-		provider: providerDetails,
-		observability: observabilityDetails,
-	};
-}
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 // Accepts `unknown` so the branded guards narrow cleanly from the top: the
 // subtype error classes are structurally compatible with ProviderError, so
 // narrowing from a ProviderError-typed value would collapse the negative branch
 // to `never`. Narrowing from unknown avoids that while still recognizing errors
 // from a duplicate SDK module instance.
-function providerObservabilityDetails(error: unknown):
-	| {
-			category: ProviderErrorCategory;
-			taxonomyVersion: string;
-			retryable: boolean;
-			upstreamStatus?: number;
-	  }
-	| undefined {
+function providerObservabilityDetails(error: unknown): ErrorObservabilityDetails | undefined {
 	// Session-expiry surfaces the credential_expired category + the opt-in
 	// retryable signal so Gateway/Credential Service can refresh and re-drive the
 	// operation (see design.md §4.3 D3). Without this branch the auth error would
@@ -751,6 +735,54 @@ function providerObservabilityDetails(error: unknown):
 	};
 }
 
+function errorObservabilityDetails(error: unknown): ErrorObservabilityDetails {
+	const providerDetails = providerObservabilityDetails(error);
+	if (providerDetails) return providerDetails;
+
+	if (error instanceof z.ZodError || isValidationError(error)) {
+		return {
+			category:
+				isProviderError(error) && error.options?.category
+					? error.options.category
+					: "input_validation",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+		};
+	}
+
+	if (error instanceof StatefulRoutingDeadlineError) {
+		return {
+			category: "timeout",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: false,
+		};
+	}
+
+	if (isProviderError(error)) {
+		return {
+			category: error.options?.category ?? "provider_error",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
+
+	return {
+		category: "internal_error",
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable: false,
+	};
+}
+
+function responseWithErrorObservability(response: Response, error: unknown): Response {
+	const headers = new Headers(response.headers);
+	headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}
+
 function publicProviderErrorMessage(error: ProviderError): string {
 	if (isTransportError(error)) {
 		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
@@ -782,11 +814,6 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return 504;
 	}
-
-	if (isTransportError(error)) {
-		return error.code === "transport_timeout" ? 504 : 502;
-	}
-
 	if (isProviderError(error)) {
 		switch (error.code) {
 			case "AUTH_REQUIRED":
@@ -812,13 +839,91 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 			case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
 				return 503;
 		}
+		if (isTransportError(error)) {
+			return error.code === "transport_timeout" ? 504 : 502;
+		}
+		if (isValidationError(error)) {
+			return error.options?.category === "output_validation" ? 500 : 400;
+		}
 
-		return 400;
+		return 500;
 	}
 
 	return 500;
 }
 
+// Codes emitted by SDK-owned paths must never be attributed to provider
+// authors by the unregistered-code signal, even when their intentional status
+// is 500. Provider-authored codes not in this registry retain the signal.
+const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+	"AUTH_PROMPT_UNAVAILABLE",
+	"BROWSER_CDP_POOL_REQUIRED",
+	"BROWSER_RUNTIME_UNSUPPORTED",
+	"STEALTH_RUNTIME_UNSUPPORTED",
+	"SSE_EVENT_UNDECLARED",
+	"STREAM_EVENT_TOO_LARGE",
+	"STREAM_CHUNK_TOO_LARGE",
+	"SSE_RESULT_UNSUPPORTED",
+	"STREAM_RESULT_UNSUPPORTED",
+	"AUTH_FLOW_NOT_CONFIGURED",
+	"refresh_not_supported",
+	"RUNTIME_UNSUPPORTED",
+	"PROVIDER_STATE_UNSUPPORTED",
+	"CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+	"CHOICE_STATE_PAYLOAD_TOO_LARGE",
+	"CHOICE_STATE_UNAVAILABLE",
+	"CHOICE_CONTEXT_REQUIRED",
+	"unsupported_stealth_cookie_store_version",
+	"provider_secret_error",
+	"credential_key_error",
+	"credential_mode_error",
+	"flow_expired",
+	"turn_validation_error",
+	"context_access_error",
+	"UNSUPPORTED_STT_OPTION",
+	"INVALID_STT_AUDIO",
+	"STT_AUDIO_TOO_LARGE",
+	"STT_UPSTREAM_FAILED",
+	"INVALID_STT_VERIFICATION_CODE_OPTIONS",
+	"NO_CODE_FOUND",
+	"AMBIGUOUS_CODE",
+	"retry_invalid_policy",
+	"retry_unsafe_method",
+	"stealth_cookie_store_serialize_failed",
+	"response_too_large",
+	"transport_stream_unavailable",
+	"transport_invalid_method",
+	"http_transport_override_unsupported",
+	"transport_invalid_url",
+	"retry_exhausted",
+	"auth_abort_unsafe_data",
+	"credentials_auth_missing_credential_keys",
+	"credentials_auth_missing_credential",
+	"credentials_auth_invalid_login_result",
+	"credentials_auth_unknown_challenge",
+	"credentials_auth_unknown_pending_challenge",
+	"STATEFUL_FORWARDING_NOT_CONFIGURED",
+	"STATEFUL_FORWARDING_SIGNATURE_MISSING",
+	"STATEFUL_FORWARDING_NONCE_INVALID",
+	"STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+	"STATEFUL_FORWARDING_SIGNATURE_INVALID",
+	"STATEFUL_FORWARDING_REPLAY_DETECTED",
+	"STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+	"STATEFUL_FORWARDING_ENVELOPE_INVALID",
+	"STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+	"STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+	"STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+	"STATEFUL_FORWARDING_REQUEST_FAILED",
+	"STATEFUL_FORWARDING_CONTEXT_MISSING",
+	"STATEFUL_FORWARDING_BAD_RESPONSE",
+	"STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+	"STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+	"STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+	"STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+	"STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+	"STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
+
 function extractRequestId(raw: unknown): string | undefined {
 	if (!raw || typeof raw !== "object") {
 		return undefined;
@@ -847,7 +952,13 @@ function logProviderError(
 				: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
-	const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+	const details = errorObservabilityDetails(error);
+	const isUnregisteredProviderErrorCode =
+		status === 500 &&
+		isProviderError(error) &&
+		!isValidationError(error) &&
+		typeof error.code === "string" &&
+		!SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
 	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
 		level: status >= 500 ? "error" : "warn",
@@ -861,15 +972,12 @@ function logProviderError(
 		code,
 		errorClass,
 		message,
-		...(isTransportError(error) && error.upstreamStatus
-			? { upstreamStatus: error.upstreamStatus }
-			: {}),
-		...(details
-			? {
-					errorCategory: details.category,
-					taxonomyVersion: details.taxonomyVersion,
-					retryable: details.retryable,
-				}
+		...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+		errorCategory: details.category,
+		taxonomyVersion: details.taxonomyVersion,
+		retryable: details.retryable,
+		...(isUnregisteredProviderErrorCode
+			? { signal: "unregistered_provider_error_code" as const }
 			: {}),
 		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
 	});
@@ -1614,17 +1722,10 @@ export function createServerApp(
 		});
 	}
 
-	app.notFound((c) =>
-		c.json(
-			{
-				error: {
-					code: "not_found",
-					message: "Not found",
-				},
-			},
-			404,
-		),
-	);
+	app.notFound((c) => {
+		const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+		return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+	});
 
 	app.get("/health", (c) =>
 		c.json({
@@ -1786,7 +1887,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1850,7 +1954,10 @@ export function createServerApp(
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1887,7 +1994,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1924,7 +2034,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1961,7 +2074,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1998,7 +2114,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -2035,7 +2154,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 

package/src/server/types.ts

@@ -26,6 +26,7 @@ export const ErrorEnvelopeSchema = z.object({
 	code: z.string(),
 	message: z.string(),
 	requestId: z.string().optional(),
+	retryable: z.boolean(),
 	fix: z.string().optional(),
 	details: z.unknown().optional(),
 });

package/src/stateful/stateful-provider-owner-forwarder.ts

@@ -35,6 +35,14 @@ type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promi
 
 const MAX_FORWARDED_HEADERS = 32;
 const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+	error: OperationErrorResponseSchema.shape.error.extend({
+		retryable: z.boolean().optional().default(false),
+	}),
+});
 const SENSITIVE_HEADER_NAMES = new Set([
 	"authorization",
 	"cookie",
@@ -253,7 +261,7 @@ async function parseForwardedResponse(response: Response): Promise<StatefulOpera
 		return { output: success.data.data };
 	}
 
-	const error = OperationErrorResponseSchema.safeParse(body);
+	const error = ForwardedOperationErrorResponseSchema.safeParse(body);
 	if (error.success) {
 		throw new StatefulOwnerForwardingError({
 			code: error.data.error.code,