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

Report provider permission denials as HTTP 403 (#1249)

Ali Khokhar4f4627414f72
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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 False
if isinstance(exc, ExecutionFailure):
return exc.retryable
- if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
+ if isinstance(
+ exc,
+ openai.AuthenticationError
+ | openai.PermissionDeniedError
+ | openai.BadRequestError,
+ ):
return False
if retryable_transient_status(exc) is not None:
return True
@@ -213,6 +221,8 @@ def provider_error_message(
return _RATE_LIMIT_MESSAGE
if isinstance(exc, openai.AuthenticationError):
return _AUTHENTICATION_MESSAGE
+ if isinstance(exc, openai.PermissionDeniedError):
+ return _PERMISSION_MESSAGE
if isinstance(exc, openai.BadRequestError):
return _INVALID_REQUEST_MESSAGE
return 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.py
index 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() -> N
assert 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.py
index 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() -> None
assert "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.lock
index 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" },