@apifuse/provider-sdk 2.2.0-beta.18 → 2.2.0-beta.20

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.20
+
+- Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
+
+## 2.2.0-beta.19
+
+- Release candidate for main commit fd93ae68d0472fae68d908312249163373ec5d22.
+
 ## 2.2.0-beta.18
 
 - Release candidate for main commit cebaf4b994918d2641c0fe6681fbffd3a3284c5d.
@@ -102,6 +110,7 @@
 
 ## Unreleased
 
+- **honest-provider-error-contract (phase 2):** `UPSTREAM_REJECTED` is a registered code family serving HTTP 409 with `retryable: false` — deterministic upstream business refusals are no longer 502s. Operation-declared `docs.errorCodes` may now use 409/410/422. Public error envelopes carry a `source` field (`client` | `upstream_rule` | `upstream_failure` | `apifuse`) derived from the observability category. Taxonomy version bumps to `2026-08-07` with the `upstream_rejected`, `dependency_unavailable`, `unsupported_transport`, and `client_cancelled` categories (409/410/422 map to `upstream_rejected`), matching the platform monorepo SoT. The `unregistered_provider_error_code` signal now carries a `signalFix` pointing at `docs.errorCodes` declaration.
 - **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
 - Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
 - Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { centered, delayed, defineHealthJourney, defineOperation, defineProvider
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
+export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
 export { type LintDiagnostic, lintOperation, lintProvider, } from "./lint.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDE
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
+export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
 export { lintOperation, lintProvider, } from "./lint.js";

package/dist/observability.d.ts

@@ -1,5 +1,8 @@
-export declare const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
-export declare const PROVIDER_ERROR_CATEGORIES: readonly ["ok", "timeout", "network", "upstream_http", "upstream_rate_limited", "upstream_auth", "upstream_schema_drift", "proxy_pool", "anti_bot_blocked", "credential_expired", "credential_unavailable", "input_validation", "output_validation", "provider_error", "internal_error", "unclassified"];
+export declare const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
+export declare const PROVIDER_ERROR_CATEGORIES: readonly ["ok", "timeout", "network", "upstream_http", "upstream_rate_limited", "upstream_auth", "upstream_rejected", "upstream_schema_drift", "proxy_pool", "anti_bot_blocked", "credential_expired", "credential_unavailable", "input_validation", "output_validation", "provider_error", "internal_error", "dependency_unavailable", "unsupported_transport", "client_cancelled", "unclassified"];
 export type ProviderErrorCategory = (typeof PROVIDER_ERROR_CATEGORIES)[number];
 export declare function categoryForStatus(status: number): ProviderErrorCategory;
 export declare function isRetryableCategory(category: ProviderErrorCategory): boolean;
+export declare const PROVIDER_ERROR_SOURCES: readonly ["client", "upstream_rule", "upstream_failure", "apifuse"];
+export type ProviderErrorSource = (typeof PROVIDER_ERROR_SOURCES)[number];
+export declare function sourceForCategory(category: ProviderErrorCategory): ProviderErrorSource;

package/dist/observability.js

@@ -1,4 +1,5 @@
-export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+// Mirrors packages/provider-observability in the platform monorepo (SoT).
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
 export const PROVIDER_ERROR_CATEGORIES = [
     "ok",
     "timeout",
@@ -6,6 +7,7 @@ export const PROVIDER_ERROR_CATEGORIES = [
     "upstream_http",
     "upstream_rate_limited",
     "upstream_auth",
+    "upstream_rejected",
     "upstream_schema_drift",
     "proxy_pool",
     "anti_bot_blocked",
@@ -15,6 +17,9 @@ export const PROVIDER_ERROR_CATEGORIES = [
     "output_validation",
     "provider_error",
     "internal_error",
+    "dependency_unavailable",
+    "unsupported_transport",
+    "client_cancelled",
     "unclassified",
 ];
 export function categoryForStatus(status) {
@@ -26,6 +31,10 @@ export function categoryForStatus(status) {
         return "upstream_rate_limited";
     if (status === 401 || status === 403)
         return "upstream_auth";
+    // provider-error-contract: 409/410/422 are the deterministic
+    // upstream-rejection status class — not a retryable upstream failure.
+    if (status === 409 || status === 410 || status === 422)
+        return "upstream_rejected";
     if (status >= 400)
         return "upstream_http";
     return "unclassified";
@@ -37,3 +46,41 @@ export function isRetryableCategory(category) {
         category === "upstream_http" ||
         category === "proxy_pool");
 }
+// Who stopped the request (honest-provider-error-contract). A deliberately
+// small public projection of the internal taxonomy:
+// - client: the request itself is fixable by the caller
+// - upstream_rule: the upstream service refused it under its own business
+//   rules (deterministic) or rate limits
+// - upstream_failure: the upstream service malfunctioned — retryable
+// - apifuse: an APIFuse-side fault (provider bug, platform dependency)
+export const PROVIDER_ERROR_SOURCES = [
+    "client",
+    "upstream_rule",
+    "upstream_failure",
+    "apifuse",
+];
+export function sourceForCategory(category) {
+    switch (category) {
+        case "input_validation":
+        case "credential_expired":
+        case "credential_unavailable":
+        case "client_cancelled":
+            return "client";
+        case "upstream_rejected":
+        case "upstream_rate_limited":
+            return "upstream_rule";
+        case "timeout":
+        case "network":
+        case "upstream_http":
+        case "upstream_auth":
+        case "upstream_schema_drift":
+        case "anti_bot_blocked":
+            return "upstream_failure";
+        default:
+            // ok never reaches error serialization; provider_error,
+            // internal_error, output_validation, proxy_pool,
+            // dependency_unavailable, unsupported_transport, unclassified are
+            // APIFuse-side faults.
+            return "apifuse";
+    }
+}

package/dist/server/serve.d.ts

@@ -87,6 +87,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     taxonomyVersion?: string;
     retryable?: boolean;
     signal?: "unregistered_provider_error_code";
+    signalFix?: string;
     issues?: Array<{
         path: string;
         code: string;

package/dist/server/serve.js

@@ -6,7 +6,7 @@ import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, } from "../error-resolution.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 { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
 import { createBrowserClient } from "../runtime/browser.js";
 import { createProviderCache } from "../runtime/cache.js";
@@ -357,8 +357,28 @@ function zodDetails(error) {
         message: issue.message,
     }));
 }
+// Category-level projection with code-aware honesty overrides: a missing
+// deployment secret is an APIFuse-side defect even though its category
+// (credential_unavailable) usually means a caller credential problem, an
+// internal stateful-routing deadline is APIFuse-owned despite its timeout
+// category, and the built-in upstream failure families keep their upstream
+// attribution even when the author left the category at the provider_error
+// default.
+function publicErrorSource(error, category) {
+    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") {
+            return "upstream_failure";
+        }
+    }
+    return sourceForCategory(category);
+}
 function toErrorResponse(error, requestId, declaredErrorCode) {
     const observability = errorObservabilityDetails(error, declaredErrorCode);
+    const source = publicErrorSource(error, observability.category);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
@@ -366,6 +386,7 @@ function toErrorResponse(error, requestId, declaredErrorCode) {
                 message: "Stateful forwarding deadline expired.",
                 ...(requestId ? { requestId } : {}),
                 retryable: observability.retryable,
+                source,
             },
         };
     }
@@ -377,6 +398,7 @@ function toErrorResponse(error, requestId, declaredErrorCode) {
                 message: publicProviderErrorMessage(error),
                 ...(requestId ? { requestId } : {}),
                 retryable: observability.retryable,
+                source,
                 ...(error.fix ? { fix: error.fix } : {}),
                 ...(details !== undefined ? { details } : {}),
             },
@@ -389,6 +411,7 @@ function toErrorResponse(error, requestId, declaredErrorCode) {
                 message: "Invalid request body",
                 ...(requestId ? { requestId } : {}),
                 retryable: observability.retryable,
+                source,
                 details: zodDetails(error),
             },
         };
@@ -405,6 +428,7 @@ function toErrorResponse(error, requestId, declaredErrorCode) {
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
             retryable: observability.retryable,
+            source,
             details: {
                 retryable: false,
                 category: "internal_error",
@@ -484,9 +508,12 @@ function errorObservabilityDetails(error, declaredErrorCode) {
         return {
             category: isProviderError(error) && error.options?.category
                 ? error.options.category
-                : isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
-                    ? "provider_error"
-                    : "input_validation",
+                : 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)
@@ -501,8 +528,18 @@ function errorObservabilityDetails(error, declaredErrorCode) {
         };
     }
     if (isProviderError(error)) {
+        // Deterministic upstream refusals default to the rejection category:
+        // the UPSTREAM_REJECTED family and any operation-declared rejection
+        // status (409/410/422) classify as upstream_rejected unless the
+        // author set an explicit category.
+        const declaredStatus = effectiveDeclaration?.status;
+        const rejectionDefault = error.code === "UPSTREAM_REJECTED" ||
+            (isEmittableErrorStatus(declaredStatus) &&
+                categoryForStatus(declaredStatus) === "upstream_rejected")
+            ? "upstream_rejected"
+            : "provider_error";
         return {
-            category: error.options?.category ?? "provider_error",
+            category: error.options?.category ?? rejectionDefault,
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
         };
@@ -579,6 +616,11 @@ function toStatusCode(error, declaredErrorCode) {
             case "UPSTREAM_RATE_LIMIT":
             case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
                 return 429;
+            // Deterministic upstream business refusal (honest-provider-error-
+            // contract): the upstream evaluated the request and said no under
+            // its own rules — a conflict with upstream state, never a 5xx.
+            case "UPSTREAM_REJECTED":
+                return 409;
             case "UPSTREAM_ERROR":
             case "BLOCKED":
                 return 502;
@@ -665,7 +707,10 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         taxonomyVersion: details.taxonomyVersion,
         retryable: details.retryable,
         ...(isUnregisteredProviderErrorCode
-            ? { signal: "unregistered_provider_error_code" }
+            ? {
+                signal: "unregistered_provider_error_code",
+                signalFix: "Declare this code (with status and retryable) in the operation's docs.errorCodes so it serves its intended status instead of 500.",
+            }
             : {}),
         ...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
     });

package/dist/server/types.d.ts

@@ -43,6 +43,12 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
     retryable: z.ZodBoolean;
+    source: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        upstream_rule: "upstream_rule";
+        upstream_failure: "upstream_failure";
+        apifuse: "apifuse";
+    }>>;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -86,6 +92,12 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
         retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -124,6 +136,12 @@ export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
         retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 import { HttpRetryPreset } from "../types.js";
 export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
 export const OperationConnectionSchema = z.object({
@@ -22,6 +23,10 @@ export const ErrorEnvelopeSchema = z.object({
     message: z.string(),
     requestId: z.string().optional(),
     retryable: z.boolean(),
+    // Who stopped the request (honest-provider-error-contract); optional so
+    // older peers (stateful forwarding owners) remain parseable. Derived from
+    // the PROVIDER_ERROR_SOURCES registry so the enum cannot drift.
+    source: z.enum(PROVIDER_ERROR_SOURCES).optional(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });

package/dist/types.d.ts

@@ -610,7 +610,7 @@ export interface HealthMonitorProbeOverride {
     /** Optional degraded threshold override for generated registry probes. */
     degradedThresholdMs?: number;
 }
-export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 429, 500, 502, 503, 504];
+export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
 export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;

package/dist/types.js

@@ -32,7 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
-export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 429, 500, 502, 503, 504];
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/package.json

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

package/src/index.ts

@@ -39,6 +39,7 @@ export {
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
+export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
 export {

package/src/observability.ts

@@ -1,4 +1,5 @@
-export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+// Mirrors packages/provider-observability in the platform monorepo (SoT).
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
 
 export const PROVIDER_ERROR_CATEGORIES = [
 	"ok",
@@ -7,6 +8,7 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"upstream_http",
 	"upstream_rate_limited",
 	"upstream_auth",
+	"upstream_rejected",
 	"upstream_schema_drift",
 	"proxy_pool",
 	"anti_bot_blocked",
@@ -16,6 +18,9 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"output_validation",
 	"provider_error",
 	"internal_error",
+	"dependency_unavailable",
+	"unsupported_transport",
+	"client_cancelled",
 	"unclassified",
 ] as const;
 
@@ -26,6 +31,9 @@ export function categoryForStatus(status: number): ProviderErrorCategory {
 	if (status === 408 || status === 504) return "timeout";
 	if (status === 429) return "upstream_rate_limited";
 	if (status === 401 || status === 403) return "upstream_auth";
+	// provider-error-contract: 409/410/422 are the deterministic
+	// upstream-rejection status class — not a retryable upstream failure.
+	if (status === 409 || status === 410 || status === 422) return "upstream_rejected";
 	if (status >= 400) return "upstream_http";
 	return "unclassified";
 }
@@ -39,3 +47,45 @@ export function isRetryableCategory(category: ProviderErrorCategory): boolean {
 		category === "proxy_pool"
 	);
 }
+
+// Who stopped the request (honest-provider-error-contract). A deliberately
+// small public projection of the internal taxonomy:
+// - client: the request itself is fixable by the caller
+// - upstream_rule: the upstream service refused it under its own business
+//   rules (deterministic) or rate limits
+// - upstream_failure: the upstream service malfunctioned — retryable
+// - apifuse: an APIFuse-side fault (provider bug, platform dependency)
+export const PROVIDER_ERROR_SOURCES = [
+	"client",
+	"upstream_rule",
+	"upstream_failure",
+	"apifuse",
+] as const;
+
+export type ProviderErrorSource = (typeof PROVIDER_ERROR_SOURCES)[number];
+
+export function sourceForCategory(category: ProviderErrorCategory): ProviderErrorSource {
+	switch (category) {
+		case "input_validation":
+		case "credential_expired":
+		case "credential_unavailable":
+		case "client_cancelled":
+			return "client";
+		case "upstream_rejected":
+		case "upstream_rate_limited":
+			return "upstream_rule";
+		case "timeout":
+		case "network":
+		case "upstream_http":
+		case "upstream_auth":
+		case "upstream_schema_drift":
+		case "anti_bot_blocked":
+			return "upstream_failure";
+		default:
+			// ok never reaches error serialization; provider_error,
+			// internal_error, output_validation, proxy_pool,
+			// dependency_unavailable, unsupported_transport, unclassified are
+			// APIFuse-side faults.
+			return "apifuse";
+	}
+}

package/src/server/serve.ts

@@ -24,6 +24,8 @@ import {
 import type { ProviderLocale } from "../i18n/keys.js";
 import {
 	categoryForStatus,
+	type ProviderErrorSource,
+	sourceForCategory,
 	isRetryableCategory,
 	PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 	type ProviderErrorCategory,
@@ -541,6 +543,7 @@ export type ProviderServerLogEvent =
 			taxonomyVersion?: string;
 			retryable?: boolean;
 			signal?: "unregistered_provider_error_code";
+			signalFix?: string;
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
 	| {
@@ -658,12 +661,34 @@ function zodDetails(error: z.ZodError): Array<{
 	}));
 }
 
+// Category-level projection with code-aware honesty overrides: a missing
+// deployment secret is an APIFuse-side defect even though its category
+// (credential_unavailable) usually means a caller credential problem, an
+// internal stateful-routing deadline is APIFuse-owned despite its timeout
+// category, and the built-in upstream failure families keep their upstream
+// attribution even when the author left the category at the provider_error
+// default.
+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") {
+			return "upstream_failure";
+		}
+	}
+	return sourceForCategory(category);
+}
+
 function toErrorResponse(
 	error: unknown,
 	requestId?: string,
 	declaredErrorCode?: OperationErrorCode,
 ): OperationErrorResponse {
 	const observability = errorObservabilityDetails(error, declaredErrorCode);
+	const source = publicErrorSource(error, observability.category);
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return {
 			error: {
@@ -671,6 +696,7 @@ function toErrorResponse(
 				message: "Stateful forwarding deadline expired.",
 				...(requestId ? { requestId } : {}),
 				retryable: observability.retryable,
+				source,
 			},
 		};
 	}
@@ -683,6 +709,7 @@ function toErrorResponse(
 				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
 				retryable: observability.retryable,
+				source,
 				...(error.fix ? { fix: error.fix } : {}),
 				...(details !== undefined ? { details } : {}),
 			},
@@ -696,6 +723,7 @@ function toErrorResponse(
 				message: "Invalid request body",
 				...(requestId ? { requestId } : {}),
 				retryable: observability.retryable,
+				source,
 				details: zodDetails(error),
 			},
 		};
@@ -713,6 +741,7 @@ function toErrorResponse(
 			message: "Internal error",
 			...(requestId ? { requestId } : {}),
 			retryable: observability.retryable,
+			source,
 			details: {
 				retryable: false,
 				category: "internal_error",
@@ -804,9 +833,12 @@ function errorObservabilityDetails(
 			category:
 				isProviderError(error) && error.options?.category
 					? error.options.category
-					: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
-						? "provider_error"
-						: "input_validation",
+					: 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)
@@ -823,8 +855,19 @@ function errorObservabilityDetails(
 	}
 
 	if (isProviderError(error)) {
+		// Deterministic upstream refusals default to the rejection category:
+		// the UPSTREAM_REJECTED family and any operation-declared rejection
+		// status (409/410/422) classify as upstream_rejected unless the
+		// author set an explicit category.
+		const declaredStatus = effectiveDeclaration?.status;
+		const rejectionDefault =
+			error.code === "UPSTREAM_REJECTED" ||
+			(isEmittableErrorStatus(declaredStatus) &&
+				categoryForStatus(declaredStatus) === "upstream_rejected")
+				? ("upstream_rejected" as const)
+				: ("provider_error" as const);
 		return {
-			category: error.options?.category ?? "provider_error",
+			category: error.options?.category ?? rejectionDefault,
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
 		};
@@ -915,6 +958,11 @@ function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): P
 			case "UPSTREAM_RATE_LIMIT":
 			case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
 				return 429;
+			// Deterministic upstream business refusal (honest-provider-error-
+			// contract): the upstream evaluated the request and said no under
+			// its own rules — a conflict with upstream state, never a 5xx.
+			case "UPSTREAM_REJECTED":
+				return 409;
 			case "UPSTREAM_ERROR":
 			case "BLOCKED":
 				return 502;
@@ -1025,7 +1073,11 @@ function logProviderError(
 		taxonomyVersion: details.taxonomyVersion,
 		retryable: details.retryable,
 		...(isUnregisteredProviderErrorCode
-			? { signal: "unregistered_provider_error_code" as const }
+			? {
+					signal: "unregistered_provider_error_code" as const,
+					signalFix:
+						"Declare this code (with status and retryable) in the operation's docs.errorCodes so it serves its intended status instead of 500.",
+				}
 			: {}),
 		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
 	});

package/src/server/types.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 
 import { HttpRetryPreset } from "../types.js";
 
@@ -27,6 +28,10 @@ export const ErrorEnvelopeSchema = z.object({
 	message: z.string(),
 	requestId: z.string().optional(),
 	retryable: z.boolean(),
+	// Who stopped the request (honest-provider-error-contract); optional so
+	// older peers (stateful forwarding owners) remain parseable. Derived from
+	// the PROVIDER_ERROR_SOURCES registry so the enum cannot drift.
+	source: z.enum(PROVIDER_ERROR_SOURCES).optional(),
 	fix: z.string().optional(),
 	details: z.unknown().optional(),
 });

package/src/types.ts

@@ -719,7 +719,7 @@ export interface HealthMonitorProbeOverride {
 	degradedThresholdMs?: number;
 }
 
-export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 429, 500, 502, 503, 504] as const;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504] as const;
 
 export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];