Add clearer warning on frontend fetching invalid backend

app/frontend_static.py

@@ -139,6 +139,18 @@ def register_frontend_static_routes(app: FastAPI, frontend_dir: Path) -> bool:
     @app.get("/{path:path}")
     async def serve_frontend(path: str):
         """Serve frontend files, falling back to index.html for SPA routing."""
+        if path == "api" or path.startswith("api/"):
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "detail": (
+                        "API endpoint not found. If you are seeing this in response to a "
+                        "frontend request, you may be running a newer frontend with an older "
+                        "backend or vice versa. A full update is suggested."
+                    )
+                },
+            )
+
         file_path = (frontend_dir / path).resolve()
         try:
             file_path.relative_to(frontend_dir)

tests/test_frontend_static.py

@@ -86,6 +86,16 @@ def test_valid_dist_serves_static_and_spa_fallback(tmp_path):
         assert "index page" in missing_response.text
         assert missing_response.headers["cache-control"] == INDEX_CACHE_CONTROL
 
+        missing_api_response = client.get("/api/not-a-real-endpoint")
+        assert missing_api_response.status_code == 404
+        assert missing_api_response.json() == {
+            "detail": (
+                "API endpoint not found. If you are seeing this in response to a frontend "
+                "request, you may be running a newer frontend with an older backend or vice "
+                "versa. A full update is suggested."
+            )
+        }
+
         asset_response = client.get("/assets/app.js")
         assert asset_response.status_code == 200
         assert "console.log('ok');" in asset_response.text