Make tool error messages actionable for the model

Errors now carry an explicit `Retry: yes|no [(<window>)]` marker plus a
numbered `Try: (1) ... (2) ... (3) ...` recovery hint, so the LLM can
decide whether to retry and what to do next instead of looping on
permanent failures or hallucinating fixes.

- Refactor utils/errors.py around _ErrorTemplate records covering
  401/403/404/422/429/500/502/503 with retryability flags and concrete
  wait windows.
- Add `recovery_hints` parameter to handle_api_error for tool-specific
  per-status overrides; wire it into all 5 tools and remove the ad-hoc
  post-call 404 overrides in search.py and chat.py.
- Each tool now points the model at the right next step on 404
  (get_data_sources, conversation_id check, fresh codebase_search, etc.).
- Expand test_error_handling.py from 10 to 17 tests, covering 422/502/
  503/timeout, recovery_hints overrides, and method-prefix propagation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rodion-m

src/tests/test_error_handling.py

@@ -6,80 +6,117 @@
 from utils.errors import handle_api_error, format_data_source_names
 
 
+def _make_http_error(status_code: int, text: str = "") -> httpx.HTTPStatusError:
+    response = MagicMock()
+    response.status_code = status_code
+    response.text = text
+    return httpx.HTTPStatusError("", request=None, response=response)
+
+
+# ---------------------------------------------------------------------------
+# Status code mapping
+# ---------------------------------------------------------------------------
+
 @pytest.mark.asyncio
 async def test_handle_401_error():
-    """Test handling of 401 authentication errors."""
+    """401 errors must be tagged non-retryable and surface API key recovery steps."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
-    # Create mock 401 response
-    response = MagicMock()
-    response.status_code = 401
-    response.text = "Invalid token"
-
-    error = httpx.HTTPStatusError("", request=None, response=response)
-    result = await handle_api_error(ctx, error, "test operation")
+    result = await handle_api_error(ctx, _make_http_error(401, "Invalid token"), "test operation")
 
     assert "Authentication error (401)" in result
     assert "Invalid API key" in result
+    # New: explicit retry decision + actionable hint
+    assert "Retry: no" in result
+    assert "Try:" in result
+    assert "CODEALIVE_API_KEY" in result
     ctx.error.assert_called_once()
 
 
 @pytest.mark.asyncio
 async def test_handle_404_error():
-    """Test handling of 404 not found errors."""
+    """404 errors must be non-retryable and point at get_data_sources."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
-    response = MagicMock()
-    response.status_code = 404
-    response.text = "Resource not found"
-
-    error = httpx.HTTPStatusError("", request=None, response=response)
-    result = await handle_api_error(ctx, error, "search")
+    result = await handle_api_error(ctx, _make_http_error(404, "Resource not found"), "search")
 
     assert "Not found error (404)" in result
+    assert "Retry: no" in result
+    assert "get_data_sources" in result
     ctx.error.assert_called_once()
 
 
 @pytest.mark.asyncio
 async def test_handle_429_rate_limit():
-    """Test handling of 429 rate limit errors."""
+    """429 errors must be retryable with a concrete wait window."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
-    response = MagicMock()
-    response.status_code = 429
-    response.text = "Rate limit exceeded"
-
-    error = httpx.HTTPStatusError("", request=None, response=response)
-    result = await handle_api_error(ctx, error, "api call")
+    result = await handle_api_error(ctx, _make_http_error(429, "Rate limit exceeded"), "api call")
 
     assert "Rate limit exceeded (429)" in result
     assert "try again later" in result
+    # New: structured retryability marker
+    assert "Retry: yes" in result
+    assert "30" in result  # mentions a concrete wait window
     ctx.error.assert_called_once()
 
 
 @pytest.mark.asyncio
 async def test_handle_500_server_error():
-    """Test handling of 500 server errors."""
+    """500 errors must be retryable and include the issues URL for persistent failures."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
-    response = MagicMock()
-    response.status_code = 500
-    response.text = "Internal server error"
-
-    error = httpx.HTTPStatusError("", request=None, response=response)
-    result = await handle_api_error(ctx, error, "operation")
+    result = await handle_api_error(ctx, _make_http_error(500, "Internal server error"), "operation")
 
     assert "Server error (500)" in result
     assert "CodeAlive service encountered an issue" in result
+    assert "Retry: yes" in result
+    assert "github.com/CodeAlive-AI/codealive-mcp/issues" in result
+
+
+@pytest.mark.asyncio
+async def test_handle_422_data_source_not_ready():
+    """422 errors must point at get_data_sources(alive_only=false)."""
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(ctx, _make_http_error(422, "still indexing"), "search")
+
+    assert "(422)" in result
+    assert "Retry: yes" in result
+    assert "alive_only=false" in result
+
+
+@pytest.mark.asyncio
+async def test_handle_502_bad_gateway():
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(ctx, _make_http_error(502), "search")
+
+    assert "(502)" in result
+    assert "Retry: yes" in result
+    assert "10" in result  # wait window mentioned
+
+
+@pytest.mark.asyncio
+async def test_handle_503_service_unavailable():
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(ctx, _make_http_error(503), "search")
+
+    assert "(503)" in result
+    assert "Retry: yes" in result
 
 
 @pytest.mark.asyncio
 async def test_handle_generic_exception():
-    """Test handling of non-HTTP exceptions."""
+    """Non-HTTP exceptions still produce a structured Retry/Try message."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
@@ -88,27 +125,96 @@ async def test_handle_generic_exception():
 
     assert "Error during parsing" in result
     assert "Invalid input" in result
-    assert "check your input parameters" in result
+    assert "Retry: no" in result
+    assert "Try:" in result
 
 
 @pytest.mark.asyncio
 async def test_handle_unknown_http_error():
-    """Test handling of unknown HTTP status codes."""
+    """Unknown 4xx codes carry the raw detail (truncated) and a 'do not retry' marker."""
     ctx = MagicMock()
     ctx.error = AsyncMock()
 
-    response = MagicMock()
-    response.status_code = 418  # I'm a teapot
-    response.text = "I'm a teapot" * 100  # Long error text
-
-    error = httpx.HTTPStatusError("", request=None, response=response)
+    error = _make_http_error(418, "I'm a teapot" * 100)
     result = await handle_api_error(ctx, error, "brewing")
 
     assert "HTTP error: 418" in result
-    # Should truncate long error messages
-    assert len(result) < 300
+    assert "Retry: no" in result
+    # Detail is capped to 200 chars; the rest of the message adds ~120 chars of structured suffix
+    assert len(result) < 400
+
+
+@pytest.mark.asyncio
+async def test_handle_timeout_error():
+    """Timeouts must be tagged retryable with explicit guidance."""
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(ctx, httpx.ReadTimeout("slow"), "search")
+
+    assert "timeout" in result.lower()
+    assert "Retry: yes" in result
+
+
+# ---------------------------------------------------------------------------
+# Per-tool recovery_hints overrides
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_recovery_hints_override_default_404():
+    """A per-tool 404 hint must replace the generic one."""
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    custom = "(1) check conversation_id, (2) drop conversation_id and retry"
+    result = await handle_api_error(
+        ctx, _make_http_error(404), "chat",
+        recovery_hints={404: custom},
+    )
+
+    assert "Not found error (404)" in result
+    assert custom in result
+    # Default 404 hint about get_data_sources is suppressed when overridden
+    assert "get_data_sources" not in result
 
 
+@pytest.mark.asyncio
+async def test_recovery_hints_only_apply_to_matching_status():
+    """A 404 override must NOT change a 401 error."""
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(
+        ctx, _make_http_error(401), "chat",
+        recovery_hints={404: "this should not appear"},
+    )
+
+    assert "Authentication error (401)" in result
+    assert "this should not appear" not in result
+    # Default 401 hint is preserved
+    assert "CODEALIVE_API_KEY" in result
+
+
+@pytest.mark.asyncio
+async def test_method_prefix_applied():
+    """The [method] prefix must be present in both returned and logged messages."""
+    ctx = MagicMock()
+    ctx.error = AsyncMock()
+
+    result = await handle_api_error(
+        ctx, _make_http_error(401), "chat",
+        method="codebase_consultant",
+    )
+
+    assert result.startswith("[codebase_consultant] Error:")
+    logged = ctx.error.call_args[0][0]
+    assert logged.startswith("[codebase_consultant] ")
+
+
+# ---------------------------------------------------------------------------
+# format_data_source_names — unchanged behaviour
+# ---------------------------------------------------------------------------
+
 def test_format_data_source_names_strings():
     """Test formatting simple string names."""
     input_data = ["id1", "id2", "id3"]
@@ -152,4 +258,3 @@ def test_format_data_source_names_empty():
     assert format_data_source_names(None) == []
     assert format_data_source_names([]) == []
     assert format_data_source_names([None, "", {}]) == []
-

src/tools/artifact_relationships.py

@@ -117,7 +117,14 @@ async def get_artifact_relationships(
 
     except (httpx.HTTPStatusError, Exception) as e:
         error_msg = await handle_api_error(
-            ctx, e, "get artifact relationships", method=_TOOL_NAME
+            ctx, e, "get artifact relationships", method=_TOOL_NAME,
+            recovery_hints={
+                404: (
+                    "(1) verify the identifier came from a recent codebase_search or fetch_artifacts result, "
+                    "(2) call codebase_search again to get a fresh identifier — the index may have changed, "
+                    "(3) check that the artifact is a function/class (relationships are not available for non-symbol artifacts)"
+                ),
+            },
         )
         return json.dumps({"error": error_msg}, separators=(",", ":"))
 

src/tools/chat.py

@@ -193,10 +193,15 @@ async def codebase_consultant(
 
     except (httpx.HTTPStatusError, Exception) as e:
         error_msg = await handle_api_error(
-            ctx, e, "chat completion", method=_TOOL_NAME
+            ctx, e, "chat completion", method=_TOOL_NAME,
+            recovery_hints={
+                404: (
+                    "(1) if continuing a conversation, verify conversation_id matches one returned by an earlier call, "
+                    "(2) if starting a new conversation, call get_data_sources to list valid data source names, "
+                    "(3) drop conversation_id and data_sources to fall back to the API key's default"
+                ),
+            },
         )
-        if isinstance(e, httpx.HTTPStatusError) and e.response.status_code == 404:
-            return f"[{_TOOL_NAME}] Error: Not found (404): The requested resource could not be found. Check your conversation_id or data_sources."
         return error_msg
 
 

src/tools/datasources.py

@@ -129,6 +129,13 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> str:
 
     except (httpx.HTTPStatusError, Exception) as e:
         error_msg = await handle_api_error(
-            ctx, e, "retrieving data sources", method=_TOOL_NAME
+            ctx, e, "retrieving data sources", method=_TOOL_NAME,
+            recovery_hints={
+                # 422 means *some* sources are still indexing — surface alive_only=false as the next step
+                422: (
+                    "(1) call get_data_sources(alive_only=false) to see which sources are still being processed, "
+                    "(2) wait a few minutes for indexing to complete and retry"
+                ),
+            },
         )
         return json.dumps({"error": error_msg}, separators=(",", ":"))

src/tools/fetch_artifacts.py

@@ -108,7 +108,14 @@ async def fetch_artifacts(
 
     except (httpx.HTTPStatusError, Exception) as e:
         error_msg = await handle_api_error(
-            ctx, e, "fetch artifacts", method=_TOOL_NAME
+            ctx, e, "fetch artifacts", method=_TOOL_NAME,
+            recovery_hints={
+                404: (
+                    "(1) verify the identifiers came from a recent codebase_search call (do not invent them), "
+                    "(2) re-run codebase_search to get fresh identifiers — the index may have changed, "
+                    "(3) for local repos in your working directory, use Read() on the file path instead"
+                ),
+            },
         )
         return f"<error>{error_msg}</error>"
 

src/tools/search.py

@@ -164,8 +164,13 @@ async def codebase_search(
 
     except (httpx.HTTPStatusError, Exception) as e:
         error_msg = await handle_api_error(
-            ctx, e, "code search", method=_TOOL_NAME
+            ctx, e, "code search", method=_TOOL_NAME,
+            recovery_hints={
+                404: (
+                    "(1) call get_data_sources to list available data source names, "
+                    "(2) check spelling and case of the names you passed in data_sources, "
+                    "(3) drop data_sources entirely to fall back to the API key's default"
+                ),
+            },
         )
-        if isinstance(e, httpx.HTTPStatusError) and e.response.status_code == 404:
-            error_msg = f"[{_TOOL_NAME}] Error: Not found (404): One or more data sources could not be found. Check your data_sources."
         return json.dumps({"error": error_msg}, separators=(",", ":"))