Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Fix misleading OpenRouter image-input errors (#1855)

Ali Khokhar8d2a431fef6e
diff --git a/pyproject.toml b/pyproject.toml
index 503eac4e..9e3e7d11 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "6.2.54"
+version = "6.2.55"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/providers/open_router/client.py b/src/free_claude_code/providers/open_router/client.py
index 27666398..1372a798 100644
--- a/src/free_claude_code/providers/open_router/client.py
+++ b/src/free_claude_code/providers/open_router/client.py
@@ -1,11 +1,13 @@
"""OpenRouter provider implementation."""
import json
+from collections.abc import Mapping
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic import ReasoningReplayMode
from free_claude_code.core.diagnostics import extract_upstream_error_detail
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.reasoning import ReasoningEffort
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
@@ -34,6 +36,35 @@ _REQUEST_POLICY = OpenAIChatRequestPolicy(
class OpenRouterChatBehavior(OpenAIChatBehavior):
"""OpenRouter Chat adaptation without HTTP ownership."""
+ def failure_override(self, error: Exception) -> ExecutionFailure | None:
+ if getattr(error, "status_code", None) != 404:
+ return None
+ body = getattr(error, "body", None)
+ if isinstance(body, Mapping) and "error" in body:
+ if any(field in body for field in ("code", "message", "metadata")):
+ return None
+ body = body["error"]
+ if not isinstance(body, Mapping):
+ return None
+ code = body.get("code")
+ if not isinstance(code, int) or code != 404:
+ return None
+ if not isinstance(body.get("message"), str):
+ return None
+ metadata = body.get("metadata")
+ if (
+ not isinstance(metadata, Mapping)
+ or metadata.get("failed_routing_step") != "Filter by Image Support"
+ ):
+ return None
+ return ExecutionFailure(
+ FailureKind.INVALID_REQUEST,
+ 400,
+ "No OpenRouter endpoint for this request supports image input. "
+ "Remove the image or choose an image-capable model.",
+ False,
+ )
+
def reasoning_disable_rejected(self, error: Exception) -> bool:
detail = extract_upstream_error_detail(error)
if detail.status_code not in {None, 200}:
diff --git a/tests/api/test_openrouter_image_errors.py b/tests/api/test_openrouter_image_errors.py
new file mode 100644
index 00000000..b92bd084
--- /dev/null
+++ b/tests/api/test_openrouter_image_errors.py
@@ -0,0 +1,81 @@
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from free_claude_code.providers.open_router import OpenRouterProvider
+from tests.api.support import create_test_app
+from tests.providers.support import immediate_admission, make_provider_config
+from tests.providers.test_open_router import image_routing_error_body, routing_error
+
+
+ ("wire", "stream"), [("messages", False), ("messages", True), ("responses", True)]
+)
[email protected]("image_rejected", [True, False])
+def test_openrouter_image_error_reaches_client_without_losing_image(
+ wire, stream, image_rejected
+):
+ provider = OpenRouterProvider(
+ make_provider_config("test-key", "https://openrouter.ai/api/v1"),
+ admission=immediate_admission(),
+ )
+ body = (
+ image_routing_error_body()
+ if image_rejected
+ else {"code": 404, "message": "Model not found"}
+ )
+ create = AsyncMock(side_effect=routing_error(body))
+ image_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl6nGQAAAAASUVORK5CYII="
+ url = f"data:image/png;base64,{image_data}"
+ payload = {"model": "open_router/test-model", "stream": stream}
+ if wire == "messages":
+ content = [
+ {"type": "text", "text": "Read this image"},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": image_data,
+ },
+ },
+ ]
+ payload.update(messages=[{"role": "user", "content": content}], max_tokens=100)
+ else:
+ content = [
+ {"type": "input_text", "text": "Read this image"},
+ {"type": "input_image", "image_url": url},
+ ]
+ payload.update(
+ input=[{"role": "user", "content": content}], max_output_tokens=100
+ )
+ try:
+ with (
+ patch(
+ "free_claude_code.api.routes.resolve_provider", return_value=provider
+ ),
+ patch.object(provider._client.chat.completions, "create", create),
+ TestClient(create_test_app()) as client,
+ ):
+ response = client.post(f"/v1/{wire}", json=payload)
+ assert response.status_code == (400 if image_rejected else 404)
+ assert response.headers["x-should-retry"] == "false"
+ error = response.json()["error"]
+ assert error["type"] == (
+ "invalid_request_error" if image_rejected else "api_error"
+ )
+ assert body["message"] in error["message"]
+ assert response.headers["request-id"] in error["message"]
+ if image_rejected:
+ assert "Remove the image" in error["message"]
+ assert create.await_count == 1
+ assert any(
+ part.get("image_url", {}).get("url") == url
+ for message in create.await_args_list[0].kwargs["messages"]
+ if isinstance(message["content"], list)
+ for part in message["content"]
+ )
+ finally:
+ asyncio.run(provider.cleanup())
diff --git a/tests/providers/test_open_router.py b/tests/providers/test_open_router.py
index 0be5ae83..e6ad1573 100644
--- a/tests/providers/test_open_router.py
+++ b/tests/providers/test_open_router.py
@@ -4,6 +4,8 @@ import json
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock, patch
+import httpx2
+import openai
import pytest
from free_claude_code.application.errors import InvalidRequestError
@@ -15,8 +17,10 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
thinking_content,
)
+from free_claude_code.core.failures import FailureKind
from free_claude_code.core.history_replay import decode_replay
from free_claude_code.core.model_capabilities import ModelInputModality
+from free_claude_code.providers.failure_policy import classify_provider_failure
from free_claude_code.providers.open_router import OpenRouterProvider
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
@@ -29,6 +33,105 @@ from tests.providers.support import (
)
+def image_routing_error_body():
+ return {
+ "message": "No endpoints found that support image input",
+ "code": 404,
+ "metadata": {"failed_routing_step": "Filter by Image Support"},
+ }
+
+
+def routing_error(body, status=404):
+ return openai.APIStatusError(
+ "OpenRouter routing failed",
+ response=httpx2.Response(
+ status,
+ request=httpx2.Request(
+ "POST", "https://openrouter.ai/api/v1/chat/completions"
+ ),
+ ),
+ body=body,
+ )
+
+
[email protected]("wrapped", [False, True])
+ "message", ["No endpoints found that support image input", "Image routing rejected"]
+)
+def test_image_routing_failure_explains_unsupported_input(
+ open_router_provider, wrapped, message
+):
+ body = {**image_routing_error_body(), "message": message}
+ error = routing_error({"error": body} if wrapped else body)
+ failure = classify_provider_failure(
+ error,
+ provider_name="OPENROUTER",
+ read_timeout_s=30,
+ request_id="req_image",
+ provider_failure_override=open_router_provider._chat._behavior.failure_override,
+ )
+ assert failure.kind == FailureKind.INVALID_REQUEST
+ assert failure.status_code == 400
+ assert failure.retryable is False
+ assert "Remove the image" in failure.message
+ assert "image-capable" in failure.message
+ assert message in failure.message
+ assert "HTTP 404" in failure.message
+ assert "req_image" in failure.message
+ assert (
+ classify_provider_failure(
+ error, provider_name="OTHER", read_timeout_s=30, request_id=None
+ ).status_code
+ == 404
+ )
+
+
+ "body",
+ [
+ {"message": "Model not found", "code": 404},
+ {**image_routing_error_body(), "metadata": {}},
+ {
+ **image_routing_error_body(),
+ "metadata": {"failed_routing_step": "Filter by Data Policy"},
+ },
+ {**image_routing_error_body(), "metadata": None},
+ {**image_routing_error_body(), "code": "404"},
+ {**image_routing_error_body(), "code": 404.0},
+ {**image_routing_error_body(), "code": 400},
+ {**image_routing_error_body(), "message": None},
+ {**image_routing_error_body(), "error": image_routing_error_body()},
+ {"error": "malformed"},
+ "No endpoints found that support image input",
+ None,
+ ],
+)
+def test_unrelated_routing_errors_keep_shared_policy(open_router_provider, body):
+ error = routing_error(body)
+ override = open_router_provider._chat._behavior.failure_override
+ assert override(error) is None
+ failure = classify_provider_failure(
+ error,
+ provider_name="OPENROUTER",
+ read_timeout_s=30,
+ request_id=None,
+ provider_failure_override=override,
+ )
+ assert failure.status_code == 404
+
+
[email protected]("status", [400, 401, 403, 429, 500, 200])
+def test_image_metadata_does_not_override_other_http_status(
+ open_router_provider, status
+):
+ assert (
+ open_router_provider._chat._behavior.failure_override(
+ routing_error(image_routing_error_body(), status)
+ )
+ is None
+ )
+
+
class AsyncStream(SDKStreamDouble):
def __init__(self, chunks):
self._chunks = chunks
diff --git a/uv.lock b/uv.lock
index 60b9b381..eac11b71 100644
--- a/uv.lock
+++ b/uv.lock
@@ -599,7 +599,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "6.2.54"
+version = "6.2.55"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },