From 718d18b68567605cb52fef2d856e834c295b663d Mon Sep 17 00:00:00 2001
From: Battleplus <3559424769@qq.com>
Date: Mon, 24 Aug 2026 00:53:18 +0800
Subject: [PATCH] fix(api): return 408 for wait_for selector timeout in /crawl
 endpoint

When crawler_config.wait_for specifies a CSS selector or JS condition
that never matches the page, smart_wait() raises TimeoutError. The
generic except Exception handler turned this into an opaque HTTP 500.

Catch TimeoutError explicitly and return 408 Request Timeout with the
original timeout message, so clients can distinguish server failures
from selector-mismatch timeouts.

Fixes #2133

Signed-off-by: Battleplus <3559424769@qq.com>
---
 deploy/docker/api.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/deploy/docker/api.py b/deploy/docker/api.py
index 1756b925f..d7871acbe 100644
--- a/deploy/docker/api.py
+++ b/deploy/docker/api.py
@@ -816,6 +816,10 @@ async def handle_crawl_request(
         # Per-crawl wall-clock deadline exceeded.
         raise HTTPException(status_code=504, detail="Crawl exceeded the time limit")
 
+    except TimeoutError as e:
+        # wait_for selector / JS condition timed out — client error, not server.
+        raise HTTPException(status_code=408, detail=str(e))
+
     except HTTPException:
         # Deliberate status (e.g. 400 SSRF "URL blocked") must pass through
         # rather than be genericized to 500 by the handler below.