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

Treat upstream HTTP 413 as terminal (#1611)

Ali Khokhar3ef17fe79d56
diff --git a/pyproject.toml b/pyproject.toml
index 14605805..64b83e0b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.17.1"
+version = "5.17.2"
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 c0488278..c4db62da 100644
--- a/src/free_claude_code/providers/failure_policy.py
+++ b/src/free_claude_code/providers/failure_policy.py
@@ -38,6 +38,7 @@ _BILLING_MESSAGE = (
)
_RATE_LIMIT_MESSAGE = "Provider rate limit reached. Please retry shortly."
_INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."
+_REQUEST_TOO_LARGE_MESSAGE = "Provider rejected the request as too large."
_CONTEXT_WINDOW_EXCEEDED_MESSAGE = "Provider input exceeds the model context window."
_OVERLOADED_MESSAGE = "Provider is currently overloaded. Please retry."
@@ -114,6 +115,8 @@ def retryable_transient_status(exc: BaseException) -> int | None:
if isinstance(exc, ExecutionFailure):
status = exc.status_code
return status if exc.retryable and _is_retryable_status(status) else None
+ if _reported_status(exc) == 413:
+ return None
if isinstance(exc, openai.RateLimitError):
return 429
if isinstance(exc, httpx.HTTPStatusError):
@@ -264,6 +267,14 @@ def _classify_provider_failure(
if isinstance(exc, ExecutionFailure):
return exc
+ if _reported_status(exc) == 413:
+ return _failure(
+ FailureKind.INVALID_REQUEST,
+ 413,
+ _REQUEST_TOO_LARGE_MESSAGE,
+ False,
+ )
+
if isinstance(exc, openai.AuthenticationError):
return _failure(FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False)
if isinstance(exc, openai.PermissionDeniedError):
@@ -377,6 +388,17 @@ def _status_from_exception(exc: BaseException) -> int | None:
return status if isinstance(status, int) else None
+def _reported_status(exc: BaseException) -> int | None:
+ status = _status_from_exception(exc)
+ if status is not None:
+ return status
+ response = getattr(exc, "response", None)
+ response_status = getattr(response, "status_code", None)
+ if isinstance(response_status, int):
+ return response_status
+ return _status_from_body(getattr(exc, "body", None))
+
+
def _status_from_body(body: Any) -> int | None:
for item in _body_candidates(body):
if not isinstance(item, Mapping):
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
index 9a04fe5e..0b021d62 100644
--- a/tests/api/test_execution_failure_contract.py
+++ b/tests/api/test_execution_failure_contract.py
@@ -516,6 +516,43 @@ def test_pre_start_permission_failure_preserves_403_without_client_retry(
assert trace["provider_retryable"] is False
+ ("path", "payload"),
+ [
+ ("/v1/messages", _messages_payload(stream=True)),
+ ("/v1/responses", _responses_payload()),
+ ],
+)
+def test_pre_start_request_too_large_failure_preserves_413(
+ path: str,
+ payload: dict[str, object],
+) -> None:
+ provider = CanonicalFailureProvider(
+ [],
+ kind=FailureKind.INVALID_REQUEST,
+ status_code=413,
+ message="Provider rejected the request as too large.",
+ retryable=False,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with resolver_patch, client:
+ response = client.post(path, json=payload)
+
+ request_id = response.headers["request-id"]
+ body = response.json()
+ assert response.status_code == 413
+ assert response.headers["x-should-retry"] == "false"
+ assert body["error"]["type"] == "request_too_large"
+ assert body["error"]["message"] == (
+ f"Provider rejected the request as too large.\n\nRequest ID: {request_id}"
+ )
+ if path == "/v1/messages":
+ assert body["request_id"] == request_id
+ else:
+ assert response.headers["x-request-id"] == request_id
+
+
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 ec93b6c7..134105e7 100644
--- a/tests/providers/test_failure_policy.py
+++ b/tests/providers/test_failure_policy.py
@@ -29,9 +29,10 @@ def _openai_status_error(
status_code: int,
message: str,
body: object | None = None,
+ headers: dict[str, str] | None = None,
) -> openai.APIStatusError:
request = httpx2.Request("POST", "https://provider.test/v1/chat/completions")
- response = httpx2.Response(status_code, request=request)
+ response = httpx2.Response(status_code, request=request, headers=headers)
return error_type(
message,
response=response,
@@ -114,6 +115,94 @@ def test_stream_retry_classification_rejects_openai_bad_request() -> None:
)
+def test_http_413_status_wins_over_rate_limit_markers() -> None:
+ error = _openai_status_error(
+ openai.APIStatusError,
+ status_code=413,
+ message="Request too large for token rate limit",
+ body={
+ "error": {
+ "message": "Request requires 55940 tokens but limit is 8000",
+ "type": "tokens",
+ "code": "rate_limit_exceeded",
+ }
+ },
+ headers={"retry-after": "67", "x-should-retry": "false"},
+ )
+
+ assert not is_retryable_provider_error(error)
+ assert not is_retryable_stream_error(error)
+ assert retryable_upstream_status(error) is None
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="GROQ",
+ read_timeout_s=60.0,
+ request_id="req_too_large",
+ )
+
+ assert failure.kind is FailureKind.INVALID_REQUEST
+ assert failure.status_code == 413
+ assert failure.retryable is False
+ assert "Provider rejected the request as too large." in failure.message
+ assert "Request requires 55940 tokens but limit is 8000" in failure.message
+ assert "Request ID: req_too_large" in failure.message
+
+
+ "error",
+ [
+ _http_status_error(413, "request too large"),
+ _statusless_openai_error(
+ "rate limit exceeded",
+ {
+ "error": {
+ "status": 413,
+ "code": "rate_limit_exceeded",
+ "message": "request too large",
+ }
+ },
+ ),
+ ],
+ ids=["httpx_status", "structured_body_status"],
+)
+def test_http_413_sources_are_terminal_invalid_requests(error: Exception) -> None:
+ assert not is_retryable_provider_error(error)
+ assert not is_retryable_stream_error(error)
+ assert retryable_upstream_status(error) is None
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="TEST_PROVIDER",
+ read_timeout_s=60.0,
+ request_id="req_413",
+ )
+
+ assert failure.kind is FailureKind.INVALID_REQUEST
+ assert failure.status_code == 413
+ assert failure.retryable is False
+ assert "Provider rejected the request as too large." in failure.message
+
+
+def test_nonstandard_capacity_status_remains_retryable() -> None:
+ error = _openai_status_error(
+ openai.APIStatusError,
+ status_code=498,
+ message="capacity exceeded",
+ body={"error": {"code": "capacity_exceeded"}},
+ )
+
+ assert retryable_upstream_status(error) == 503
+ failure = classify_provider_failure(
+ error,
+ provider_name="GROQ",
+ read_timeout_s=60.0,
+ request_id="req_capacity",
+ )
+ assert failure.kind is FailureKind.OVERLOADED
+ assert failure.retryable is True
+
+
@dataclass(frozen=True, slots=True)
class _ClassificationCase:
name: str
diff --git a/tests/providers/test_provider_admission.py b/tests/providers/test_provider_admission.py
index cf975b00..c6d404c4 100644
--- a/tests/providers/test_provider_admission.py
+++ b/tests/providers/test_provider_admission.py
@@ -8,6 +8,8 @@ from email.utils import format_datetime
from unittest.mock import patch
import httpx
+import httpx2
+import openai
import pytest
from free_claude_code.core.failures import ExecutionFailure, FailureKind
@@ -456,6 +458,51 @@ async def test_non_retryable_error_is_attempted_once() -> None:
assert attempts == 1
+async def test_openai_413_does_not_retry_sleep_or_open_recovery() -> None:
+ controller = _controller()
+ attempts = 0
+ request = httpx2.Request("POST", "https://provider.test/chat/completions")
+ response = httpx2.Response(
+ 413,
+ request=request,
+ headers={"retry-after": "237", "x-should-retry": "false"},
+ )
+ error = openai.APIStatusError(
+ "Request too large for token rate limit",
+ response=response,
+ body={
+ "error": {
+ "type": "tokens",
+ "code": "rate_limit_exceeded",
+ "message": "Request requires 55940 tokens but limit is 8000",
+ }
+ },
+ )
+
+ async def reject() -> None:
+ nonlocal attempts
+ attempts += 1
+ raise error
+
+ with (
+ patch("free_claude_code.providers.admission.asyncio.sleep") as sleep,
+ patch("free_claude_code.providers.admission.trace_event") as trace,
+ pytest.raises(openai.APIStatusError),
+ ):
+ await controller.start_execution(request_id="req_413").run_call(
+ reject,
+ operation_kind=ProviderOperationKind.GENERATION,
+ )
+
+ assert attempts == 1
+ sleep.assert_not_awaited()
+ assert all(
+ call.kwargs.get("event") != "provider.recovery.opened"
+ for call in trace.call_args_list
+ )
+
+
@pytest.mark.asyncio
async def test_pre_response_protocol_failure_opens_coordinated_recovery() -> None:
controller = _controller()
diff --git a/uv.lock b/uv.lock
index 5a208a7e..6fb03c0c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.17.1"
+version = "5.17.2"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },