Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(library): classify 202 and resolved-URL download failures (#6324)

Ehsan505f19b5c7a2
diff --git a/changelog.d/5950.bugfix.md b/changelog.d/5950.bugfix.md
new file mode 100644
index 0000000000..910644d02e
--- /dev/null
+++ b/changelog.d/5950.bugfix.md
@@ -0,0 +1 @@
+Two PDF-download failure shapes that used to fall through the failure classifier as `unknown_error` now have their own classifications. A publisher answering 202 (request accepted, not yet ready), whether it arrives as a status code or only in the error message, is classified as `processing` and retried after 30 minutes instead of an hour. An open-access URL that resolved but would not download is classified as `download_failed`, retryable on the same one-hour cooldown as before. Both stop emitting the `[FAILURE_CLASSIFIER] Unclassified error` warning; existing paywall, forbidden and timeout classifications are unchanged.
diff --git a/src/local_deep_research/library/download_management/failure_classifier.py b/src/local_deep_research/library/download_management/failure_classifier.py
index 26c773e53f..b1a205fca3 100644
--- a/src/local_deep_research/library/download_management/failure_classifier.py
+++ b/src/local_deep_research/library/download_management/failure_classifier.py
@@ -111,6 +111,12 @@ class FailureClassifier:
"""
# HTTP Status Code classifications
if status_code:
+ if status_code == 202:
+ return TemporaryFailure(
+ "processing",
+ "Request accepted but not yet ready (202)",
+ timedelta(minutes=30),
+ )
if status_code == 404:
return PermanentFailure("not_found", "Resource not found (404)")
if status_code == 403:
@@ -189,6 +195,18 @@ class FailureClassifier:
"forbidden", "Access denied based on error message"
)
+ # Queued/processing patterns in error messages (without status code)
+ if (
+ "error code 202" in details_lower
+ or "http 202" in details_lower
+ or "status code 202" in details_lower
+ ):
+ return TemporaryFailure(
+ "processing",
+ "Request accepted but not yet ready based on error message",
+ timedelta(minutes=30),
+ )
+
# Common timeout and network errors
if "timeout" in error_lower or "timed out" in details_lower:
return TemporaryFailure(
@@ -201,6 +219,14 @@ class FailureClassifier:
timedelta(minutes=5),
)
+ # Fetch that failed after a URL was resolved; last so narrower branches win
+ if "download failed" in details_lower:
+ return TemporaryFailure(
+ "download_failed",
+ "Resolved URL could not be downloaded",
+ timedelta(hours=1),
+ )
+
# Default to temporary failure with 1-hour cooldown
logger.warning(
f"[FAILURE_CLASSIFIER] Unclassified error: {error_type} - {details}"
diff --git a/tests/library/download_management/test_failure_classifier_extended.py b/tests/library/download_management/test_failure_classifier_extended.py
index 96c1d09a96..cd0e88f7d1 100644
--- a/tests/library/download_management/test_failure_classifier_extended.py
+++ b/tests/library/download_management/test_failure_classifier_extended.py
@@ -555,3 +555,79 @@ class TestEdgeCases:
assert isinstance(failure2, PermanentFailure)
assert failure2.error_type == "incompatible_format"
+
+
+class TestQueuedAndDownloadFailureShapes:
+ """Tests for the two shapes reported in #5950"""
+
+ def test_classify_error_code_202_in_message(self):
+ """Test a 202 reported in the message is retryable after 30 minutes"""
+ classifier = FailureClassifier()
+ failure = classifier.classify_failure(
+ error_type="str",
+ url="https://journal.example.com/article/123",
+ details=(
+ "PDF extraction failed: Unable to access article - "
+ "server returned error code 202"
+ ),
+ )
+
+ assert isinstance(failure, TemporaryFailure)
+ assert failure.error_type == "processing"
+ assert failure.retry_after == timedelta(minutes=30)
+ assert failure.is_permanent() is False
+
+ def test_classify_http_202_status_code(self):
+ """Test a 202 status code is retryable after 30 minutes"""
+ classifier = FailureClassifier()
+ failure = classifier.classify_failure(
+ error_type="http_error",
+ status_code=202,
+ url="https://journal.example.com/article/123",
+ )
+
+ assert isinstance(failure, TemporaryFailure)
+ assert failure.error_type == "processing"
+ assert failure.retry_after == timedelta(minutes=30)
+ assert "202" in failure.message
+
+ def test_classify_open_access_download_failure(self):
+ """Test a resolved URL that would not download gets its own type"""
+ classifier = FailureClassifier()
+ failure = classifier.classify_failure(
+ error_type="str",
+ url="https://doi.org/10.1000/example",
+ details=(
+ "PDF extraction failed: Open access PDF URL found but "
+ "download failed"
+ ),
+ )
+
+ assert isinstance(failure, TemporaryFailure)
+ assert failure.error_type == "download_failed"
+ assert failure.retry_after == timedelta(hours=1)
+ assert failure.is_permanent() is False
+
+ def test_paywall_still_wins_over_download_failure(self):
+ """Test the download-failure branch does not shadow the paywall one"""
+ classifier = FailureClassifier()
+ failure = classifier.classify_failure(
+ error_type="str",
+ url="https://journal.example.com/article/123",
+ details="Article requires subscription, download failed",
+ )
+
+ assert isinstance(failure, PermanentFailure)
+ assert failure.error_type == "paywall_or_login"
+
+ def test_unrelated_message_still_unclassified(self):
+ """Test messages matching neither shape keep the unknown_error path"""
+ classifier = FailureClassifier()
+ failure = classifier.classify_failure(
+ error_type="str",
+ url="https://journal.example.com/article/123",
+ details="Server error (500) - website is experiencing technical issues",
+ )
+
+ assert failure.error_type == "unknown_error"
+ assert failure.retry_after == timedelta(hours=1)