Clarify ambiguous 413 scan failures

Author: lelia

CHANGELOG.md

@@ -7,8 +7,8 @@
 - The 200-character cap on the commit message now applies to the value read from the
   repository, not only to `--commit-message`. A truncated message ends in `...` and the
   truncation is reported at INFO.
-- A full scan refused for its size (HTTP 413, 414 or 431) now reports which value to
-  shorten.
+- A full scan refused for its size (HTTP 413, 414 or 431) now distinguishes possible
+  upload-size and request-metadata causes and reports what to shorten.
 
 ## 2.9.6
 

socketsecurity/core/__init__.py

@@ -113,11 +113,10 @@
 FULL_SCAN_UPLOAD_MAX_ATTEMPTS = len(FULL_SCAN_UPLOAD_BACKOFF_SCHEDULE_SECONDS)
 FULL_SCAN_UPLOAD_BACKOFF_JITTER_SECONDS = 2.0
 
-# Statuses that mean the request line itself was rejected before the API read it: the
-# scan metadata (commit message, branch, committers) travels in the query string of the
-# full-scan POST, so an oversized value is refused by the proxy in front of the API. The
-# proxy picks the code -- 413 (payload), 414 (URI), 431 (headers) -- so all three map to
-# the same cause. Not transient: every retry sends the same oversized URL.
+# Statuses that mean the request is too large to process. Scan metadata travels in the
+# query string of the full-scan POST, while manifests travel in its multipart body. A
+# 413 can refer to either part; 414 points to the URL, and some proxies report 431 when
+# the encoded request target exceeds their header limit. None are transient.
 REQUEST_TOO_LARGE_STATUS_CODES = (413, 414, 431)
 
 # Diff-scan polling policy. The legacy scan comparison (fullscans.stream_diff) holds a
@@ -1126,12 +1125,20 @@ def create_full_scan(self, files: List[str], params: FullScanParams, base_paths:
                     break
                 except APIFailure as error:
                     if error.status_code in REQUEST_TOO_LARGE_STATUS_CODES:
+                        if error.status_code == 413:
+                            guidance = (
+                                "The response does not distinguish between an oversized multipart "
+                                "upload and oversized scan metadata in the request URL. Reduce the "
+                                "uploaded scan inputs, or pass a shorter --commit-message."
+                            )
+                        else:
+                            guidance = (
+                                "Scan metadata is sent in the request URL. Pass a shorter "
+                                "--commit-message or shorten other scan metadata."
+                            )
                         raise APIFailure(
                             f"Full scan request rejected as too large (HTTP {error.status_code}). "
-                            "Scan metadata is sent in the request URL, so an oversized value -- "
-                            "most often the commit message -- is refused by the proxy in front of "
-                            "the API before the request is read. Pass a shorter --commit-message "
-                            f"to work around it.\n{error}",
+                            f"{guidance}\n{error}",
                             status_code=error.status_code,
                         ) from error
                     if backoff_seconds is None or not error.is_transient_error():

tests/unit/test_full_scan_retry.py

@@ -285,15 +285,13 @@ def test_retry_decision_delegates_to_sdk_classification(
     assert core_with_mock_sdk.sdk.fullscans.post.call_count == expected_calls
 
 
-@pytest.mark.parametrize("status_code", [413, 414, 431])
-def test_oversized_request_is_not_retried_and_names_the_cause(
+@pytest.mark.parametrize("status_code", [414, 431])
+def test_oversized_request_target_is_not_retried_and_names_the_cause(
     core_with_mock_sdk, tmp_path, no_sleep, status_code
 ):
     """
-    A proxy that refuses the request line reports 413, 414 or 431 depending on which limit
-    it checks. None of them are worth a retry (the same oversized URL goes back out), and
-    the SDK's own message is a status code plus the proxy's response body, which does not
-    say what to change.
+    URI and header size failures are deterministic for the same request, and the SDK's
+    message does not say which metadata to shorten.
     """
     manifest = tmp_path / "package.json"
     manifest.write_text("{}")
@@ -310,3 +308,21 @@ def test_oversized_request_is_not_retried_and_names_the_cause(
     # The SDK's original text is kept so the proxy's own response stays available.
     assert f"original_status_code:{status_code}" in message
     assert exc_info.value.status_code == status_code
+
+
+def test_413_reports_upload_and_metadata_causes(core_with_mock_sdk, tmp_path, no_sleep):
+    manifest = tmp_path / "package.json"
+    manifest.write_text("{}")
+    core_with_mock_sdk.sdk.fullscans.post.side_effect = _catch_all_failure(413)
+
+    with pytest.raises(APIFailure) as exc_info:
+        core_with_mock_sdk.create_full_scan([str(manifest)], MagicMock())
+
+    assert core_with_mock_sdk.sdk.fullscans.post.call_count == 1
+    no_sleep.assert_not_called()
+    message = str(exc_info.value)
+    assert "oversized multipart upload" in message
+    assert "oversized scan metadata" in message
+    assert "--commit-message" in message
+    assert "original_status_code:413" in message
+    assert exc_info.value.status_code == 413