@kortyx/openrouter 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @kortyx/openrouter
 
+## Unreleased
+
+### Bug Fixes
+
+- Report confirmed parameter-routing 404s as `PROVIDER_PARAMETER_UNSUPPORTED`,
+  including requested parameter names, tool/output versus other controls and
+  the automatic/explicit/default source of `requireParameters`. Explain the
+  existing explicit override and preset visibility limits. Preserve original
+  developer-facing messages and private SDK causes; recognize numeric/string
+  codes and structured routing evidence. Surface malformed SDK responses as
+  `PROVIDER_INVALID_RESPONSE` with partial usage. Keep request defaults and
+  automatic retry behavior unchanged.
+
+
+## [0.2.6](https://github.com/kortyx-io/kortyx/compare/openrouter-v0.2.5...openrouter-v0.2.6) (2026-10-13)
+
+
+### Bug Fixes
+
+* **openrouter:** explain parameter routing failures ([#338](https://github.com/kortyx-io/kortyx/issues/338)) ([193a287](https://github.com/kortyx-io/kortyx/commit/193a28794b6f05626a2d69148fa8592fcd5956e9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.14.0
+    * @kortyx/providers bumped to 0.9.3
+
 ## [0.2.5](https://github.com/kortyx-io/kortyx/compare/openrouter-v0.2.4...openrouter-v0.2.5) (2026-10-11)
 
 

package/README.md

@@ -38,6 +38,45 @@ OpenRouter-specific request controls belong under
 `provider.requireParameters` when a request uses function tools or a native
 JSON schema, unless the caller explicitly chooses another value.
 
+This is an all-parameter requirement: optional controls such as `temperature`
+must also be supported by the selected endpoint. The default is unchanged.
+
+Parameter-routing refusals use `PROVIDER_PARAMETER_UNSUPPORTED`. The safe failure
+explains whether `requireParameters` was enabled automatically for tools/native
+JSON schemas, explicitly configured by the caller, or left at the provider default.
+It lists tool/output parameters (`response_format`, `tools`, `tool_choice`)
+separately from other requested controls. These lists identify what was sent;
+they do not claim which parameter caused the rejection or which controls your
+application can safely omit.
+
+Remove controls your application can omit, or choose a compatible route. The
+error names this existing, explicit override when Kortyx enabled strict routing:
+
+```ts
+const model = openrouter("anthropic/claude-sonnet-4.6", {
+  providerOptions: {
+    openrouter: { provider: { requireParameters: false } },
+  },
+});
+```
+
+With that override, unsupported controls may be ignored, including tools and
+structured output. Kortyx does not remove parameters or retry a modified request.
+
+Preset aliases can add settings on OpenRouter's side. The diagnostic warns that
+its list only covers parameters sent by Kortyx; it does not fetch or change
+presets, publish customer-chosen preset/model names, or identify a requested alias
+as the resolved model.
+
+For developer debugging, the live exception preserves the original provider
+message and original SDK error as `cause`, including its status, stack and
+metadata. Public failure descriptors contain the safe explanation and allowlisted
+parameter names, excluding prompts, parameter values and account routing data.
+Numeric/string 404 codes and structured parameter-filter evidence are recognized;
+unrelated 404s retain their existing classification. If the SDK rejects a malformed
+response and no parameter refusal can be established, `PROVIDER_INVALID_RESPONSE`
+retains the SDK parsing error. Partial stream usage is preserved.
+
 ```ts
 const model = openrouter("anthropic/claude-sonnet-4.6", {
   providerOptions: {

package/dist/index.cjs

@@ -5412,6 +5412,16 @@ function createOpenRouterClient(settings, apiKey) {
 // src/errors.ts
 var import_errors = require("@kortyx/core/errors");
 var import_errors2 = require("@kortyx/core/errors");
+var rawEnvelope = (error) => {
+  const raw = (0, import_errors.errorProperty)(error, "rawValue");
+  if (typeof raw !== "string") return raw;
+  if (raw.length > import_errors.FAILURE_LIMITS.bytes) return void 0;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+};
 var requireApiKey = (apiKey) => {
   if (!apiKey || apiKey.trim().length === 0) {
     throw new import_errors.ProviderConfigurationError(
@@ -5420,7 +5430,115 @@ var requireApiKey = (apiKey) => {
   }
   return apiKey;
 };
-var toProviderRequestError = (action, error) => (0, import_errors.normalizeProviderError)("openrouter", action, error);
+var parameterNames = (request) => {
+  const parameters = {
+    temperature: request.temperature,
+    top_p: request.topP,
+    top_k: request.topK,
+    frequency_penalty: request.frequencyPenalty,
+    presence_penalty: request.presencePenalty,
+    repetition_penalty: request.repetitionPenalty,
+    min_p: request.minP,
+    top_a: request.topA,
+    stop: request.stop,
+    seed: request.seed,
+    max_tokens: request.maxTokens,
+    max_completion_tokens: request.maxCompletionTokens,
+    reasoning: request.reasoning,
+    response_format: request.responseFormat,
+    tools: request.tools,
+    tool_choice: request.toolChoice,
+    logprobs: request.logprobs,
+    top_logprobs: request.topLogprobs,
+    logit_bias: request.logitBias,
+    parallel_tool_calls: request.parallelToolCalls,
+    prediction: request.prediction,
+    modalities: request.modalities,
+    image_config: request.imageConfig,
+    reasoning_effort: request.reasoningEffort
+  };
+  return Object.entries(parameters).filter(([, value]) => value !== void 0).map(([name]) => name);
+};
+var toProviderRequestError = (action, error, request, context) => {
+  if (request && !(0, import_errors.isControlFlowError)(error)) {
+    const envelope = rawEnvelope(error);
+    const detail = (0, import_errors.errorProperty)(error, "error") ?? (0, import_errors.errorProperty)(envelope, "error") ?? error;
+    const metadata2 = (0, import_errors.errorProperty)(detail, "metadata");
+    const routing = (0, import_errors.errorProperty)(metadata2, "routing_funnel") ?? (0, import_errors.errorProperty)(
+      (0, import_errors.errorProperty)(error, "openrouterMetadata") ?? (0, import_errors.errorProperty)(error, "openrouter_metadata") ?? (0, import_errors.errorProperty)(envelope, "openrouter_metadata"),
+      "routing_funnel"
+    );
+    const failedRoutingStep = (0, import_errors.errorProperty)(routing, "failed_routing_step") ?? (0, import_errors.errorProperty)(metadata2, "failed_routing_step");
+    const rawStatus = (0, import_errors.errorProperty)(error, "statusCode") ?? (0, import_errors.errorProperty)(detail, "code");
+    const status = typeof rawStatus === "number" || typeof rawStatus === "string" ? Number(rawStatus) : void 0;
+    const message = (0, import_errors.errorProperty)(detail, "message") ?? (0, import_errors.errorProperty)(error, "message");
+    const parameterFilter = typeof failedRoutingStep === "string" && failedRoutingStep.trim().toLowerCase() === "filter by parameters";
+    const parameterMessage = typeof message === "string" && /^no endpoints found that can handle the requested parameters\.?$/i.test(
+      message.trim()
+    );
+    if (status === 404 && (parameterFilter || failedRoutingStep === void 0 && parameterMessage)) {
+      const requestedParameters = parameterNames(request);
+      const requireParameters = request.provider?.requireParameters ?? false;
+      const requireParametersSource = context?.requireParametersSource ?? "unknown";
+      const featureNames = /* @__PURE__ */ new Set(["response_format", "tools", "tool_choice"]);
+      const featureParameters = requestedParameters.filter(
+        (name2) => featureNames.has(name2)
+      );
+      const otherParameters = requestedParameters.filter(
+        (name2) => !featureNames.has(name2)
+      );
+      const usesPreset = Boolean(
+        request.model?.includes("@preset/") || request.models?.some((model) => model.includes("@preset/"))
+      );
+      const automaticFeatures = [
+        ...request.tools?.length ? ["tool calling"] : [],
+        ...request.responseFormat?.type === "json_schema" ? ["structured output"] : []
+      ];
+      const origin = requireParametersSource === "automatic" ? `enabled automatically by Kortyx for ${automaticFeatures.join(" and ")}` : requireParametersSource === "explicit" ? "configured explicitly by the caller" : requireParametersSource === "default" ? "not explicitly set; provider default" : "setting origin unavailable";
+      const guidance = "Remove unsupported optional parameters only if your application can omit them, or select a compatible model/provider route.";
+      const override = requireParametersSource === "automatic" ? " To override strict parameter routing, set providerOptions.openrouter.provider.requireParameters=false; unsupported controls, including tools/structured output, may then be ignored." : "";
+      const preset = usesPreset ? " Preset settings may also affect routing; this list only covers parameters sent by Kortyx." : "";
+      const diagnostic = `OpenRouter found no endpoint supporting the requested parameters. require_parameters=${requireParameters} (${origin}). Tool/output parameters: ${featureParameters.join(", ") || "none"}. Other requested parameters: ${otherParameters.join(", ") || "none"}. ${guidance}${override}${preset}`;
+      return new import_errors.ProviderRequestError(
+        typeof message === "string" ? message : diagnostic,
+        {
+          code: "PROVIDER_PARAMETER_UNSUPPORTED",
+          source: "openrouter",
+          operation: action,
+          status: 404,
+          retryable: false,
+          safeMessage: diagnostic,
+          details: {
+            requestedParameters,
+            requireParameters,
+            requireParametersSource,
+            featureParameters,
+            otherParameters,
+            usesPreset,
+            ...parameterFilter ? { failedRoutingStep: "Filter by Parameters" } : {}
+          },
+          cause: error
+        }
+      );
+    }
+  }
+  const name = (0, import_errors.errorProperty)(error, "name");
+  const originalMessage = (0, import_errors.errorProperty)(error, "message");
+  if (name === "ResponseValidationError" || context?.streamStarted && (name === "SDKValidationError" || name === "ZodError")) {
+    return new import_errors.ProviderRequestError(
+      typeof originalMessage === "string" ? originalMessage : "OpenRouter SDK response validation failed.",
+      {
+        code: "PROVIDER_INVALID_RESPONSE",
+        source: "openrouter",
+        operation: action,
+        retryable: false,
+        safeMessage: "OpenRouter returned a response that did not match its SDK schema. Inspect the original SDK error for details.",
+        cause: error
+      }
+    );
+  }
+  return (0, import_errors.normalizeProviderError)("openrouter", action, error);
+};
 
 // src/messages.ts
 var isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -5485,9 +5603,10 @@ var toTool = (tool) => ({
     strict: false
   }
 });
-var createChatRequest = (modelId, messages, options, stream) => {
+var prepareChatRequest = (modelId, messages, options, stream) => {
   const extra = getOpenRouterOptions(options);
   const needsRequiredParameters = Boolean(options.tools?.length) || options.responseFormat?.type === "json" && options.responseFormat.schema !== void 0;
+  const requireParametersSource = extra.provider?.requireParameters !== void 0 ? "explicit" : needsRequiredParameters ? "automatic" : "default";
   const provider = {
     ...extra.provider,
     ...needsRequiredParameters && extra.provider?.requireParameters === void 0 ? { requireParameters: true } : {}
@@ -5499,7 +5618,7 @@ var createChatRequest = (modelId, messages, options, stream) => {
     } : {},
     ...options.reasoning.includeThoughts ? { summary: "auto" } : {}
   } : extra.reasoning;
-  return {
+  const request = {
     ...extra,
     model: modelId,
     messages: toMessages(messages),
@@ -5521,6 +5640,7 @@ var createChatRequest = (modelId, messages, options, stream) => {
     ...options.tools?.length ? { tools: options.tools.map(toTool) } : {},
     ...Object.keys(provider).length > 0 ? { provider } : {}
   };
+  return { request, context: { requireParametersSource } };
 };
 
 // src/models.ts
@@ -5849,18 +5969,23 @@ var createChatModel = (modelId, settings, options) => {
   return {
     supportsToolStreaming: true,
     async invoke(messages) {
+      let request;
+      let context;
       try {
-        const response = await getClient().chat(
-          createChatRequest(modelId, messages, options, false),
-          options.abortSignal
-        );
+        ({ request, context } = prepareChatRequest(
+          modelId,
+          messages,
+          options,
+          false
+        ));
+        const response = await getClient().chat(request, options.abortSignal);
         if (isAsyncIterable(response))
           throw new import_errors2.ProviderRequestError(
             "OpenRouter unexpectedly returned a stream for a non-streaming request."
           );
         return resultFrom(modelId, response, warnings);
       } catch (error) {
-        throw toProviderRequestError("invoke content", error);
+        throw toProviderRequestError("invoke content", error, request, context);
       }
     },
     async *stream(messages) {
@@ -5881,15 +6006,21 @@ var createChatModel = (modelId, settings, options) => {
       }
       let lastChunk;
       let partialUsage;
+      let request;
+      let context;
       try {
-        const response = await getClient().chat(
-          createChatRequest(modelId, messages, options, true),
-          options.abortSignal
-        );
+        ({ request, context } = prepareChatRequest(
+          modelId,
+          messages,
+          options,
+          true
+        ));
+        const response = await getClient().chat(request, options.abortSignal);
         if (!isAsyncIterable(response))
           throw new import_errors2.ProviderRequestError(
             "OpenRouter unexpectedly returned a non-streaming response for a streaming request."
           );
+        context.streamStarted = true;
         const calls = /* @__PURE__ */ new Map();
         const reasoningDetails = [];
         let finishReason;
@@ -5897,9 +6028,12 @@ var createChatModel = (modelId, settings, options) => {
           lastChunk = chunk;
           partialUsage = mapUsage2(chunk.usage) ?? partialUsage;
           if (chunk.error)
-            throw new import_errors2.ProviderRequestError(chunk.error.message, {
-              ...chunk.error.metadata ? { details: chunk.error.metadata } : {}
-            });
+            throw toProviderRequestError(
+              "stream content",
+              chunk.error,
+              request,
+              context
+            );
           for (const choice of chunk.choices) {
             finishReason = choice.finishReason ?? finishReason;
             if (choice.delta.content)
@@ -5962,7 +6096,7 @@ var createChatModel = (modelId, settings, options) => {
         yield {
           type: "error",
           error: Object.assign(
-            toProviderRequestError("stream content", error),
+            toProviderRequestError("stream content", error, request, context),
             {
               usage: partialUsage
             }