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
Report provider permission denials as HTTP 403 (#1249)
Ali Khokhar4f4627414f72
diff --git a/pyproject.toml b/pyproject.tomlindex 2130730d..4cabfb0b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.12.2"+version = "4.12.3"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/failure_policy.py b/src/free_claude_code/providers/failure_policy.pyindex 2d33839e..3bc10ee2 100644--- a/src/free_claude_code/providers/failure_policy.py+++ b/src/free_claude_code/providers/failure_policy.py@@ -30,6 +30,9 @@ _OVERLOAD_MARKERS = frozenset()_INTERNAL_ERROR_MARKERS = frozenset({"internal_server_error", "internal server error"})_AUTHENTICATION_MESSAGE = "Provider authentication failed. Check API key."+_PERMISSION_MESSAGE = (+ "Provider denied access. Check credential permissions and model access."+)_RATE_LIMIT_MESSAGE = "Provider rate limit reached. Please retry shortly."_INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."_CONTEXT_WINDOW_EXCEEDED_MESSAGE = "Provider input exceeds the model context window."@@ -160,7 +163,12 @@ def is_retryable_provider_error(exc: BaseException) -> bool:return Falseif isinstance(exc, ExecutionFailure):return exc.retryable- if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):+ if isinstance(+ exc,+ openai.AuthenticationError+ | openai.PermissionDeniedError+ | openai.BadRequestError,+ ):return Falseif retryable_transient_status(exc) is not None:return True@@ -213,6 +221,8 @@ def provider_error_message(return _RATE_LIMIT_MESSAGEif isinstance(exc, openai.AuthenticationError):return _AUTHENTICATION_MESSAGE+ if isinstance(exc, openai.PermissionDeniedError):+ return _PERMISSION_MESSAGEif isinstance(exc, openai.BadRequestError):return _INVALID_REQUEST_MESSAGEreturn safe_exception_message(exc)@@ -228,6 +238,8 @@ def _classify_provider_failure(if isinstance(exc, openai.AuthenticationError):return _failure(FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False)+ if isinstance(exc, openai.PermissionDeniedError):+ return _failure(FailureKind.PERMISSION, 403, _PERMISSION_MESSAGE, False)if isinstance(exc, openai.RateLimitError):return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)if isinstance(exc, openai.BadRequestError):@@ -259,6 +271,12 @@ def _classify_provider_failure(effective_status = status or getattr(exc, "status_code", None)if not isinstance(effective_status, int):effective_status = 500+ if effective_status == 401:+ return _failure(+ FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False+ )+ if effective_status == 403:+ return _failure(FailureKind.PERMISSION, 403, _PERMISSION_MESSAGE, False)return _failure(FailureKind.UPSTREAM,effective_status,@@ -268,10 +286,12 @@ def _classify_provider_failure(if isinstance(exc, httpx.HTTPStatusError):status = exc.response.status_code- if status in (401, 403):+ if status == 401:return _failure(FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False)+ if status == 403:+ return _failure(FailureKind.PERMISSION, 403, _PERMISSION_MESSAGE, False)if status == 429:return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)if status == 400:diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.pyindex 32e98be4..f502b672 100644--- a/tests/api/test_execution_failure_contract.py+++ b/tests/api/test_execution_failure_contract.py@@ -265,6 +265,51 @@ def test_messages_pre_start_execution_failure_is_correlated_terminal_json() -> Nassert provider.stream_kwargs[0]["request_id"] == request_id+ ("path", "payload"),+ [+ ("/v1/messages", _messages_payload(stream=True)),+ ("/v1/responses", _responses_payload()),+ ],+)+def test_pre_start_permission_failure_preserves_403_without_client_retry(+ path: str,+ payload: dict[str, object],+) -> None:+ provider = CanonicalFailureProvider(+ [],+ kind=FailureKind.PERMISSION,+ status_code=403,+ message="Provider denied access.",+ retryable=False,+ )+ resolver_patch, client = _client_for(provider)++ with (+ resolver_patch,+ patch("free_claude_code.api.response_streams.trace_event") as trace_mock,+ client,+ ):+ response = client.post(path, json=payload)++ request_id = response.headers["request-id"]+ error = response.json()["error"]+ assert response.status_code == 403+ assert response.headers["x-should-retry"] == "false"+ assert error["type"] == "permission_error"+ assert error["message"] == f"Provider denied access.\n\nRequest ID: {request_id}"+ if path == "/v1/messages":+ assert response.json()["request_id"] == request_id+ assert "x-request-id" not in response.headers+ else:+ assert response.headers["x-request-id"] == request_id+ trace = _terminal_trace(trace_mock)+ assert trace["failure_kind"] == "permission"+ assert trace["status_code"] == 403+ assert trace["error_type"] == "permission_error"+ assert trace["provider_retryable"] is False++def test_messages_context_window_failure_triggers_client_compaction() -> None:provider = CanonicalFailureProvider([],diff --git a/tests/providers/test_failure_policy.py b/tests/providers/test_failure_policy.pyindex e2cba6f9..ed6243ce 100644--- a/tests/providers/test_failure_policy.py+++ b/tests/providers/test_failure_policy.py@@ -75,6 +75,39 @@ _CASES = (401,False,),+ _ClassificationCase(+ "openai_permission_denied",+ lambda: _openai_status_error(+ openai.PermissionDeniedError,+ status_code=403,+ message="Forbidden",+ ),+ FailureKind.PERMISSION,+ 403,+ False,+ ),+ _ClassificationCase(+ "generic_openai_401",+ lambda: _openai_status_error(+ openai.APIStatusError,+ status_code=401,+ message="Unauthorized",+ ),+ FailureKind.AUTHENTICATION,+ 401,+ False,+ ),+ _ClassificationCase(+ "generic_openai_403",+ lambda: _openai_status_error(+ openai.APIStatusError,+ status_code=403,+ message="Forbidden",+ ),+ FailureKind.PERMISSION,+ 403,+ False,+ ),_ClassificationCase("openai_rate_limit",lambda: _openai_status_error(@@ -150,12 +183,19 @@ _CASES = (False,),_ClassificationCase(- "http_403_keeps_authentication_quirk",- lambda: _http_status_error(403, "Forbidden"),+ "http_401_maps_authentication",+ lambda: _http_status_error(401, "Unauthorized"),FailureKind.AUTHENTICATION,401,False,),+ _ClassificationCase(+ "http_403_maps_permission",+ lambda: _http_status_error(403, "Forbidden"),+ FailureKind.PERMISSION,+ 403,+ False,+ ),_ClassificationCase("http_502_keeps_overload_quirk",lambda: _http_status_error(502, "Bad gateway"),@@ -277,6 +317,39 @@ def test_auth_failure_preserves_model_error_body_instead_of_masking_it() -> Noneassert "Request ID: req_model" in failure.message+def test_permission_failure_preserves_actionable_upstream_diagnostic() -> None:+ error = _openai_status_error(+ openai.PermissionDeniedError,+ status_code=403,+ message="Forbidden",+ body={+ "status": 403,+ "title": "Forbidden",+ "detail": "Authorization failed",+ },+ )++ failure = classify_provider_failure(+ error,+ provider_name="NIM",+ read_timeout_s=60.0,+ request_id="req_permission",+ )++ assert failure.kind is FailureKind.PERMISSION+ assert failure.status_code == 403+ assert failure.retryable is False+ assert not is_retryable_provider_error(error)+ assert "Upstream provider NIM returned HTTP 403." in failure.message+ assert "Category: permission" in failure.message+ assert (+ "Mapped message: Provider denied access. "+ "Check credential permissions and model access."+ ) in failure.message+ assert '"detail":"Authorization failed"' in failure.message+ assert "Request ID: req_permission" in failure.message++def test_empty_http_error_body_is_reported_explicitly() -> None:request = httpx.Request("POST", "https://provider.test/v1/messages")response = httpx.Response(500, request=request, content=b"")diff --git a/uv.lock b/uv.lockindex 27b6344f..93047424 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.12.2"+version = "4.12.3"source = { editable = "." }dependencies = [{ name = "aiohttp" },