@apifuse/provider-sdk 2.2.0-beta.15 → 2.2.0-beta.16

package/AUTHORING.md

@@ -411,12 +411,14 @@ Provider-server failures use a stable public envelope:
 
 `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.
+an explicit `true` or `false` wins over the matching operation declaration and
+SDK derivation. When it is omitted, `operations.<id>.docs.errorCodes[].retryable`
+is used for a matching provider-owned code, followed by SDK derivation (which
+defaults ordinary `ProviderError` values 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,
@@ -435,8 +437,41 @@ 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`:
+Declare provider-owned operation failures next to their documentation. The
+server builds a lookup once at startup and applies it to failures from that
+operation:
+
+```ts
+docs: {
+  errorCodes: [{
+    code: "UPSTREAM_SCHEMA_ERROR",
+    status: 502,
+    retryable: true,
+    description: "The upstream response no longer matches its schema.",
+  }],
+},
+handler: async () => {
+  throw new ProviderError("Upstream schema changed", {
+    code: "UPSTREAM_SCHEMA_ERROR",
+  });
+},
+```
+
+`defineProvider` accepts only statuses the server can emit: 400, 401, 404, 429,
+500, 502, 503, and 504. Invalid declared statuses fail provider definition,
+not a live request. Status selection uses this order:
+
+1. SDK-owned errors retain SDK status semantics. Operation declarations cannot
+   override SDK-owned codes, stateful-forwarding failures, Zod/deadline errors,
+   or `TransportError` values.
+2. A matching operation `errorCodes` entry with `status` supplies the status.
+   This slot applies to `ValidationError` as well as ordinary `ProviderError`.
+3. The registered mappings below apply.
+4. Existing fallbacks apply: `TransportError` 502/504, unregistered input
+   `ValidationError` 400 (output validation 500), and other unregistered
+   `ProviderError` values 500.
+
+The registered mappings are:
 
 | Error code or fallback | HTTP status |
 | --- | ---: |
@@ -451,11 +486,15 @@ including `ValidationError`:
 
 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.
+structured failure log. A matching operation declaration, including one that
+omits `status`, makes the code registered for this signal and may independently
+supply `retryable`. The HTTP 400 `ValidationError` behavior is only the fallback
+when neither an operation status nor a registered mapping applies.
+
+Throw the domain `ProviderError` directly. Subclassing or wrapping it as a
+`TransportError` solely to preserve a 5xx response is obsolete; declare the
+domain code's `status` instead. Genuine `TransportError` values remain
+SDK-owned and keep their 502/504 mapping.
 
 ### Declared secrets are SDK-enforced
 

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.16
+
+- Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
+
 ## 2.2.0-beta.15
 
 - Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
@@ -90,6 +94,7 @@
 
 ## Unreleased
 
+- 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.
 - Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
 - **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.

package/dist/define.js

@@ -1,9 +1,10 @@
 import ms from "ms";
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
 import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
-import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, 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";
+import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, 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, VALID_OPERATION_ERROR_STATUSES, } from "./types.js";
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"];
@@ -410,6 +411,23 @@ function validateOperationObservability(providerId, operations) {
         }
     }
 }
+function validateOperationErrorCodes(providerId, operations) {
+    for (const [operationName, operation] of Object.entries(operations)) {
+        for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+            if (errorCode.status !== undefined &&
+                !VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)) {
+                const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`, {
+                    fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+                });
+            }
+            if (errorCode.status !== undefined &&
+                SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)) {
+                console.warn(`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`);
+            }
+        }
+    }
+}
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
     "kind",
@@ -1396,6 +1414,7 @@ export function defineProvider(config) {
     validateOperationIds(config.id, config.operations);
     validateOperationAnnotations(config.id, config.operations);
     validateOperationObservability(config.id, config.operations);
+    validateOperationErrorCodes(config.id, config.operations);
     validateOperationTransports(config.id, config.operations);
     validateOperationContracts(config.id, config.operations);
     validateToolRouterMetadata(config.id, config.operations);

package/dist/error-resolution.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
+export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;

package/dist/error-resolution.js

@@ -0,0 +1,90 @@
+// This set suppresses the unregistered-provider-error-code signal for codes
+// intentionally emitted by SDK paths. It is not the complete authority for
+// runtime error resolution: branded errors and additional canonical SDK codes
+// must also remain immune to provider-declared status/retryability overrides.
+export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+    "MISSING_SECRET",
+    "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",
+    "http_redirect_policy_invalid",
+    "http_redirect_stopped",
+    "http_redirect_max_hops",
+    "http_redirect_missing_location",
+    "http_redirect_loop",
+    "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",
+]);
+// Complete code authority for provider-declared runtime resolution. Keep this
+// separate from signal suppression: declarations may document these codes, but
+// their status and retryability can never override the SDK's canonical result.
+export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
+    ...SDK_OWNED_PROVIDER_ERROR_CODES,
+    "reauth_required",
+    "STT_UNAVAILABLE",
+    "UNSUPPORTED_STT_BACKEND",
+    "OUTPUT_VALIDATION_FAILED",
+    "NOT_FOUND",
+    "not_found",
+]);

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 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, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, 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, RedirectRunReason, 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";
+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, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, 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, ProviderErrorStatus, 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, RedirectRunReason, 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";
 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";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/provider.d.ts

@@ -7,6 +7,6 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.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 type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
 export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/server/serve.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 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";
@@ -29,6 +30,7 @@ import { STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER, STATEFUL_SIG
 import { StatefulRoutingDeadlineError } from "../stateful/stateful-provider-session-routing.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
+import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import { createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
@@ -353,8 +355,8 @@ function zodDetails(error) {
         message: issue.message,
     }));
 }
-function toErrorResponse(error, requestId) {
-    const observability = errorObservabilityDetails(error);
+function toErrorResponse(error, requestId, declaredErrorCode) {
+    const observability = errorObservabilityDetails(error, declaredErrorCode);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
@@ -414,7 +416,10 @@ function toErrorResponse(error, requestId) {
 // 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) {
+function providerObservabilityDetails(error, declaredErrorCode) {
+    const declaredRetryable = sdkOwnsErrorResolution(error)
+        ? undefined
+        : declaredErrorCode?.retryable;
     // 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
@@ -424,7 +429,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     // Missing-secret errors carry the canonical credential_unavailable category
@@ -436,7 +441,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_unavailable",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     if (!isTransportError(error)) {
@@ -467,17 +472,23 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
-function errorObservabilityDetails(error) {
-    const providerDetails = providerObservabilityDetails(error);
+function errorObservabilityDetails(error, declaredErrorCode) {
+    const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
+    const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
     if (providerDetails)
         return providerDetails;
     if (error instanceof z.ZodError || isValidationError(error)) {
+        const declaredStatus = effectiveDeclaration?.status;
         return {
             category: isProviderError(error) && error.options?.category
                 ? error.options.category
-                : "input_validation",
+                : isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+                    ? "provider_error"
+                    : "input_validation",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+            retryable: isProviderError(error)
+                ? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+                : false,
         };
     }
     if (error instanceof StatefulRoutingDeadlineError) {
@@ -491,7 +502,7 @@ function errorObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "provider_error",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
         };
     }
     return {
@@ -500,9 +511,9 @@ function errorObservabilityDetails(error) {
         retryable: false,
     };
 }
-function responseWithErrorObservability(response, error) {
+function responseWithErrorObservability(response, error, declaredErrorCode) {
     const headers = new Headers(response.headers);
-    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)));
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -534,7 +545,11 @@ function publicProviderErrorMessage(error) {
     }
     return error.message;
 }
-function toStatusCode(error) {
+function isEmittableErrorStatus(value) {
+    return (typeof value === "number" &&
+        VALID_OPERATION_ERROR_STATUSES.some((status) => status === value));
+}
+function toStatusCode(error, declaredErrorCode) {
     if (error instanceof z.ZodError) {
         return 400;
     }
@@ -542,6 +557,10 @@ function toStatusCode(error) {
         return 504;
     }
     if (isProviderError(error)) {
+        if (!sdkOwnsErrorResolution(error) &&
+            isEmittableErrorStatus(declaredErrorCode?.status)) {
+            return declaredErrorCode.status;
+        }
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -576,82 +595,32 @@ function toStatusCode(error) {
     }
     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",
-    "http_redirect_policy_invalid",
-    "http_redirect_stopped",
-    "http_redirect_max_hops",
-    "http_redirect_missing_location",
-    "http_redirect_loop",
-    "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 sdkOwnsErrorResolution(error) {
+    if (isSessionExpiredError(error))
+        return true;
+    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));
+}
+function buildOperationErrorCodeLookup(provider) {
+    return new Map(Object.entries(provider.operations).flatMap(([operationId, operation]) => {
+        const errorCodes = operation.docs?.errorCodes;
+        return errorCodes?.length
+            ? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))]]
+            : [];
+    }));
+}
+function declaredErrorCodeFor(error, operationId, lookup) {
+    if (!operationId || !isProviderError(error) || typeof error.code !== "string")
+        return undefined;
+    return lookup.get(operationId)?.get(error.code);
+}
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -659,7 +628,7 @@ function extractRequestId(raw) {
     const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
     return typeof value === "string" ? value : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
@@ -669,12 +638,13 @@ 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 = errorObservabilityDetails(error);
+    const details = errorObservabilityDetails(error, declaredErrorCode);
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
         !isValidationError(error) &&
         typeof error.code === "string" &&
-        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+        declaredErrorCode === undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -1270,6 +1240,7 @@ export function createServerApp(provider, options = {}) {
     validateStatefulServerConfig(options);
     const app = new Hono();
     const logger = options.logger ?? defaultProviderServerLogger;
+    const operationErrorCodes = buildOperationErrorCodeLookup(provider);
     const statefulForwardingReplayCache = new StatefulForwardingReplayCache(options.statefulForwarding?.replayCacheMaxEntries ??
         DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES);
     const state = options.state ??
@@ -1303,6 +1274,7 @@ export function createServerApp(provider, options = {}) {
     app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
         let rawBodyText = "";
         let rawBody;
+        let operationId;
         const operation = "stateful-internal";
         const requestCost = startRequestCost();
         try {
@@ -1388,7 +1360,7 @@ export function createServerApp(provider, options = {}) {
                 });
             }
             const request = operationRequestFromForwardingEnvelope(envelope);
-            const operationId = envelope.operationId;
+            operationId = envelope.operationId;
             const ctx = createProviderContext(provider, request, operationId, options, state);
             if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
                 throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt);
@@ -1405,13 +1377,14 @@ export function createServerApp(provider, options = {}) {
             return c.json({ data: output });
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
                 c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
             }
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            logProviderError(logger, provider, "operation", operationId || operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1439,13 +1412,14 @@ export function createServerApp(provider, options = {}) {
             return c.json(response);
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/auth/start", async (c) => {

package/dist/types.d.ts

@@ -610,9 +610,11 @@ 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 type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;
-    status?: number;
+    status?: ProviderErrorStatus;
     description: string;
     retryable?: boolean;
 }

package/dist/types.js

@@ -32,6 +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 HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/package.json

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

package/src/define.ts

@@ -1,5 +1,6 @@
 import ms from "ms";
 
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import {
 	NativeEgressPolicyValidationError,
@@ -56,6 +57,7 @@ import {
 	STREAM_IDLE_TIMEOUT_MS_MIN,
 	STREAM_MAX_DURATION_MS_MAX,
 	STREAM_MAX_DURATION_MS_MIN,
+	VALID_OPERATION_ERROR_STATUSES,
 } from "./types.js";
 
 type ProviderImplementationSourceAccess =
@@ -800,6 +802,36 @@ function validateOperationObservability(
 	}
 }
 
+function validateOperationErrorCodes(
+	providerId: string,
+	operations: Record<string, ProviderOperation>,
+): void {
+	for (const [operationName, operation] of Object.entries(operations)) {
+		for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+			if (
+				errorCode.status !== undefined &&
+				!VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)
+			) {
+				const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`,
+					{
+						fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+					},
+				);
+			}
+			if (
+				errorCode.status !== undefined &&
+				SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)
+			) {
+				console.warn(
+					`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`,
+				);
+			}
+		}
+	}
+}
+
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
 	"kind",
@@ -2185,6 +2217,7 @@ export function defineProvider<
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
 	validateOperationObservability(config.id, config.operations);
+	validateOperationErrorCodes(config.id, config.operations);
 	validateOperationTransports(config.id, config.operations);
 	validateOperationContracts(config.id, config.operations);
 	validateToolRouterMetadata(config.id, config.operations);

package/src/error-resolution.ts

@@ -0,0 +1,91 @@
+// This set suppresses the unregistered-provider-error-code signal for codes
+// intentionally emitted by SDK paths. It is not the complete authority for
+// runtime error resolution: branded errors and additional canonical SDK codes
+// must also remain immune to provider-declared status/retryability overrides.
+export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+	"MISSING_SECRET",
+	"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",
+	"http_redirect_policy_invalid",
+	"http_redirect_stopped",
+	"http_redirect_max_hops",
+	"http_redirect_missing_location",
+	"http_redirect_loop",
+	"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",
+]);
+
+// Complete code authority for provider-declared runtime resolution. Keep this
+// separate from signal suppression: declarations may document these codes, but
+// their status and retryability can never override the SDK's canonical result.
+export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
+	...SDK_OWNED_PROVIDER_ERROR_CODES,
+	"reauth_required",
+	"STT_UNAVAILABLE",
+	"UNSUPPORTED_STT_BACKEND",
+	"OUTPUT_VALIDATION_FAILED",
+	"NOT_FOUND",
+	"not_found",
+]);

package/src/index.ts

@@ -230,6 +230,7 @@ export type {
 	OperationDeprecationMetadata,
 	OperationDocMeta,
 	OperationErrorCode,
+	ProviderErrorStatus,
 	OperationHandlerResult,
 	OperationInputExample,
 	OperationLifecycle,

package/src/provider.ts

@@ -123,6 +123,7 @@ export type {
 	OperationDefinition,
 	OperationDocMeta,
 	OperationErrorCode,
+	ProviderErrorStatus,
 	OperationInputExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,

package/src/server/serve.ts

@@ -4,6 +4,10 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import {
+	SDK_OWNED_PROVIDER_ERROR_CODES,
+	SDK_RUNTIME_OWNED_ERROR_CODES,
+} from "../error-resolution.js";
 import {
 	AuthError,
 	isProviderError,
@@ -79,8 +83,10 @@ import type {
 	FlowContextStore,
 	HttpRetrySummary,
 	OperationDefinition,
+	OperationErrorCode,
 	OperationHttpStreamTransport,
 	OperationSseTransport,
+	ProviderErrorStatus,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderProxyPolicy,
@@ -89,6 +95,7 @@ import type {
 	StealthClient,
 	SttContext,
 } from "../types.js";
+import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import {
 	createSelfTestApp,
 	createSelfTestAuthFlowInvoke,
@@ -644,8 +651,12 @@ function zodDetails(error: z.ZodError): Array<{
 	}));
 }
 
-function toErrorResponse(error: unknown, requestId?: string): OperationErrorResponse {
-	const observability = errorObservabilityDetails(error);
+function toErrorResponse(
+	error: unknown,
+	requestId?: string,
+	declaredErrorCode?: OperationErrorCode,
+): OperationErrorResponse {
+	const observability = errorObservabilityDetails(error, declaredErrorCode);
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return {
 			error: {
@@ -709,7 +720,13 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 // 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): ErrorObservabilityDetails | undefined {
+function providerObservabilityDetails(
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails | undefined {
+	const declaredRetryable = sdkOwnsErrorResolution(error)
+		? undefined
+		: declaredErrorCode?.retryable;
 	// 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
@@ -719,7 +736,7 @@ function providerObservabilityDetails(error: unknown): ErrorObservabilityDetails
 		return {
 			category: error.options?.category ?? "credential_expired",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? false,
+			retryable: error.options?.retryable ?? declaredRetryable ?? false,
 		};
 	}
 	// Missing-secret errors carry the canonical credential_unavailable category
@@ -731,7 +748,7 @@ function providerObservabilityDetails(error: unknown): ErrorObservabilityDetails
 		return {
 			category: error.options?.category ?? "credential_unavailable",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? false,
+			retryable: error.options?.retryable ?? declaredRetryable ?? false,
 		};
 	}
 	if (!isTransportError(error)) {
@@ -766,18 +783,27 @@ function providerObservabilityDetails(error: unknown): ErrorObservabilityDetails
 	};
 }
 
-function errorObservabilityDetails(error: unknown): ErrorObservabilityDetails {
-	const providerDetails = providerObservabilityDetails(error);
+function errorObservabilityDetails(
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails {
+	const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
+	const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
 	if (providerDetails) return providerDetails;
 
 	if (error instanceof z.ZodError || isValidationError(error)) {
+		const declaredStatus = effectiveDeclaration?.status;
 		return {
 			category:
 				isProviderError(error) && error.options?.category
 					? error.options.category
-					: "input_validation",
+					: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+						? "provider_error"
+						: "input_validation",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+			retryable: isProviderError(error)
+				? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+				: false,
 		};
 	}
 
@@ -793,7 +819,7 @@ function errorObservabilityDetails(error: unknown): ErrorObservabilityDetails {
 		return {
 			category: error.options?.category ?? "provider_error",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-			retryable: error.options?.retryable ?? false,
+			retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
 		};
 	}
 
@@ -804,9 +830,16 @@ function errorObservabilityDetails(error: unknown): ErrorObservabilityDetails {
 	};
 }
 
-function responseWithErrorObservability(response: Response, error: unknown): Response {
+function responseWithErrorObservability(
+	response: Response,
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): Response {
 	const headers = new Headers(response.headers);
-	headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+	headers.set(
+		ERROR_OBSERVABILITY_HEADER,
+		JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)),
+	);
 	return new Response(response.body, {
 		status: response.status,
 		statusText: response.statusText,
@@ -838,7 +871,14 @@ function publicProviderErrorMessage(error: ProviderError): string {
 	return error.message;
 }
 
-function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 | 504 {
+function isEmittableErrorStatus(value: unknown): value is ProviderErrorStatus {
+	return (
+		typeof value === "number" &&
+		VALID_OPERATION_ERROR_STATUSES.some((status) => status === value)
+	);
+}
+
+function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): ProviderErrorStatus {
 	if (error instanceof z.ZodError) {
 		return 400;
 	}
@@ -846,6 +886,12 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 		return 504;
 	}
 	if (isProviderError(error)) {
+		if (
+			!sdkOwnsErrorResolution(error) &&
+			isEmittableErrorStatus(declaredErrorCode?.status)
+		) {
+			return declaredErrorCode.status;
+		}
 		switch (error.code) {
 			case "AUTH_REQUIRED":
 			case "reauth_required":
@@ -883,82 +929,39 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 	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",
-	"http_redirect_policy_invalid",
-	"http_redirect_stopped",
-	"http_redirect_max_hops",
-	"http_redirect_missing_location",
-	"http_redirect_loop",
-	"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 sdkOwnsErrorResolution(error: unknown): boolean {
+	if (isSessionExpiredError(error)) return true;
+	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)
+	);
+}
+
+type OperationErrorCodeLookup = ReadonlyMap<string, ReadonlyMap<string, OperationErrorCode>>;
+
+function buildOperationErrorCodeLookup(provider: ProviderDefinition): OperationErrorCodeLookup {
+	return new Map(
+		Object.entries(provider.operations).flatMap(([operationId, operation]) => {
+			const errorCodes = operation.docs?.errorCodes;
+			return errorCodes?.length
+				? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))] as const]
+				: [];
+		}),
+	);
+}
+
+function declaredErrorCodeFor(
+	error: unknown,
+	operationId: string | undefined,
+	lookup: OperationErrorCodeLookup,
+): OperationErrorCode | undefined {
+	if (!operationId || !isProviderError(error) || typeof error.code !== "string") return undefined;
+	return lookup.get(operationId)?.get(error.code);
+}
 
 function extractRequestId(raw: unknown): string | undefined {
 	if (!raw || typeof raw !== "object") {
@@ -978,6 +981,7 @@ function logProviderError(
 	error: unknown,
 	status: number,
 	cost: ProviderRequestCost,
+	declaredErrorCode?: OperationErrorCode,
 ): void {
 	const code = isProviderError(error)
 		? (error.code ?? "provider_error")
@@ -988,13 +992,14 @@ function logProviderError(
 				: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
-	const details = errorObservabilityDetails(error);
+	const details = errorObservabilityDetails(error, declaredErrorCode);
 	const isUnregisteredProviderErrorCode =
 		status === 500 &&
 		isProviderError(error) &&
 		!isValidationError(error) &&
 		typeof error.code === "string" &&
-		!SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
+		!SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+		declaredErrorCode === undefined;
 	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
 		level: status >= 500 ? "error" : "warn",
@@ -1729,6 +1734,7 @@ export function createServerApp(
 	validateStatefulServerConfig(options);
 	const app = new Hono();
 	const logger = options.logger ?? defaultProviderServerLogger;
+	const operationErrorCodes = buildOperationErrorCodeLookup(provider);
 	const statefulForwardingReplayCache = new StatefulForwardingReplayCache(
 		options.statefulForwarding?.replayCacheMaxEntries ??
 			DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES,
@@ -1774,6 +1780,7 @@ export function createServerApp(
 	app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
 		let rawBodyText = "";
 		let rawBody: unknown;
+		let operationId: string | undefined;
 		const operation = "stateful-internal";
 		const requestCost = startRequestCost();
 		try {
@@ -1884,7 +1891,7 @@ export function createServerApp(
 				});
 			}
 			const request = operationRequestFromForwardingEnvelope(envelope);
-			const operationId = envelope.operationId;
+			operationId = envelope.operationId;
 			const ctx = createProviderContext(provider, request, operationId, options, state);
 			if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
 				throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt as string);
@@ -1908,7 +1915,8 @@ export function createServerApp(
 			);
 			return c.json({ data: output });
 		} catch (error) {
-			const status = toStatusCode(error);
+			const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
+			const status = toStatusCode(error, declaredErrorCode);
 			if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
 				c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
 			}
@@ -1917,15 +1925,17 @@ export function createServerApp(
 				logger,
 				provider,
 				"operation",
-				operation,
+				operationId || operation,
 				requestId,
 				error,
 				status,
 				finishRequestCost(requestCost),
+				declaredErrorCode,
 			);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
+				c.json(toErrorResponse(error, requestId, declaredErrorCode), status),
 				error,
+				declaredErrorCode,
 			);
 		}
 	});
@@ -1976,7 +1986,8 @@ export function createServerApp(
 			);
 			return c.json(response);
 		} catch (error) {
-			const status = toStatusCode(error);
+			const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
+			const status = toStatusCode(error, declaredErrorCode);
 			const requestId = extractRequestId(rawBody);
 			logProviderError(
 				logger,
@@ -1987,12 +1998,14 @@ export function createServerApp(
 				error,
 				status,
 				finishRequestCost(requestCost),
+				declaredErrorCode,
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return responseWithErrorObservability(
-				c.json(toErrorResponse(error, requestId), status),
+				c.json(toErrorResponse(error, requestId, declaredErrorCode), status),
 				error,
+				declaredErrorCode,
 			);
 		}
 	});

package/src/types.ts

@@ -719,9 +719,13 @@ export interface HealthMonitorProbeOverride {
 	degradedThresholdMs?: number;
 }
 
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 429, 500, 502, 503, 504] as const;
+
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
+
 export interface OperationErrorCode {
 	code: string;
-	status?: number;
+	status?: ProviderErrorStatus;
 	description: string;
 	retryable?: boolean;
 }