Test: release Go-proxy RESTful contract tests verified passing in Go mode (#17468)

### Summary Aligns Go and Python error codes/messages so both backends honor the same RESTful API contract, removing implementation-specific error leaks (MySQL errors, `ValueError`, `AttributeError`, Gin validator format) in favor of clean business error codes. **Chat list** — invalid `orderby` now returns code 101 (was: raw Python `AttributeError` code 100); invalid `page`/`page_size` values fall back to defaults (was: raw `ValueError`/`ProgrammingError` code 100). **Dataset create/update/delete** — adds UUID validation (101), extra-field rejection (101), duplicate-id detection (101), content-type / JSON-syntax / object-shape checks (101), and "lacks permission" for nonexistent datasets (IDOR). Create auto-deduplicates dataset names. Pagerank updates tolerate a missing ES index. List response includes `parser_config` and `pagerank`. **Session list/update** — adds filtering, sorting, and pagination support. Empty payloads are valid no-ops. Authorization errors map to code 109. **Chunk list** — doc object uses Python key names (`chunk_count`, `dataset_id`, `chunk_method`, run text status). Add validates list element types. **Document update** — adds `chunk_method` alias, pydantic-style Field error messages, metadata index auto-create with refresh, and "These documents do not belong to dataset" messages. List validates `metadata_condition` and reports ownership errors for unmatched name/id filters. **Search completion** — `kb_ids` ownership failure returns code 102 instead of 109. Released 31 contract tests from `GO_ONLY_SKIPS` (all verified passing on both Go and Python backends with real LLM keys).
2026-08-02 05:47:31 +08:00 · 2026-07-30 19:58:49 +08:00
parent 75ac8cec2e
commit 8fc20dd9ca
53 changed files with 1138 additions and 426 deletions
--- a/internal/handler/api_token.go
+++ b/internal/handler/api_token.go
@@ -17,6 +17,8 @@
 package handler

 import (
+	"errors"
+	"io"
 	"net/http"
 	"ragflow/internal/common"
 	"ragflow/internal/dao"
@@ -89,9 +91,10 @@ func (h *SystemHandler) CreateKey(c *gin.Context) {

 	tenantID := tenants[0].TenantID

-	// Parse request
+	// Parse request. An empty body is valid (all fields are optional);
+	// ShouldBind reports io.EOF for it.
 	var req service.CreateAPIKeyRequest
-	if err = c.ShouldBind(&req); err != nil {
+	if err = c.ShouldBind(&req); err != nil && !errors.Is(err, io.EOF) {
 		common.ResponseWithHttpCodeData(c, http.StatusBadRequest, 400, nil, "Invalid request")
 		return
 	}
--- a/internal/handler/auth.go
+++ b/internal/handler/auth.go
@@ -60,7 +60,7 @@ func NewAuthHandler() *AuthHandler {
 //  1. Beta API token         → GetUserByBetaAPIToken
 //  2. JWT (regular session) → existing UserService.GetUserByToken
 //  3. API token              → GetUserByAPIToken
-//  4. Fall through           → 401
+//  4. Fall through           → code 102 "Authorization is not valid!"
 //
 // IMPORTANT: the regular-user branch is NOT gated on a "Bearer "
 // prefix. UserService.GetUserByToken accepts the raw Authorization
@@ -79,7 +79,9 @@ func (h *AuthHandler) BetaAuthMiddleware() gin.HandlerFunc {
 		}

 		if auth == "" {
-			common.ResponseWithCodeData(c, common.CodeUnauthorized, nil, "Authorization required")
+			// Mirror Python's login_required(auth_types=AUTH_BETA): any auth
+			// failure on beta endpoints is a business error, not an HTTP 401.
+			common.ResponseWithCodeData(c, common.CodeDataError, nil, "Authorization is not valid!")
 			c.Abort()
 			return
 		}
@@ -105,7 +107,8 @@ func (h *AuthHandler) BetaAuthMiddleware() gin.HandlerFunc {
 			c.Next()
 			return
 		}
-		common.ResponseWithCodeData(c, common.CodeUnauthorized, nil, "Invalid auth credentials")
+		// Mirror Python's login_required(auth_types=AUTH_BETA).
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, "Authorization is not valid!")
 		c.Abort()
 	}
 }
--- a/internal/handler/auth_test.go
+++ b/internal/handler/auth_test.go
@@ -49,18 +49,20 @@ func TestBetaAuthMiddleware_MissingHeader(t *testing.T) {
 	if rec.Code != http.StatusOK {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
 	}
-	// jsonError writes 200 with a CodeUnauthorized body. Confirm the
-	// body shape matches the wire contract used by the rest of the
-	// bot handlers by decoding the JSON envelope and asserting the
-	// code field rather than just checking for a non-empty body.
+	// Beta endpoints follow Python's login_required(auth_types=AUTH_BETA):
+	// auth failures are business errors (code 102), not HTTP 401.
 	var resp struct {
-		Code common.ErrorCode `json:"code"`
+		Code    common.ErrorCode `json:"code"`
+		Message string           `json:"message"`
 	}
 	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
 		t.Fatalf("unmarshal response: %v; body = %s", err, rec.Body.String())
 	}
-	if resp.Code != common.CodeUnauthorized {
+	if resp.Code != common.CodeDataError {
 		t.Errorf("code = %d, want %d; body = %s",
-			resp.Code, common.CodeUnauthorized, rec.Body.String())
+			resp.Code, common.CodeDataError, rec.Body.String())
+	}
+	if resp.Message != "Authorization is not valid!" {
+		t.Errorf("message = %q; body = %s", resp.Message, rec.Body.String())
 	}
 }
--- a/internal/handler/chat.go
+++ b/internal/handler/chat.go
@@ -96,10 +96,16 @@ func (h *ChatHandler) ListChats(c *gin.Context) {
 	}

 	orderby := c.DefaultQuery("orderby", "create_time")
+	switch orderby {
+	case "create_time", "update_time", "name":
+	default:
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("invalid orderby field: %s", orderby))
+		return
+	}

 	desc := true
 	if descStr := c.Query("desc"); descStr != "" {
-		desc = descStr != "false"
+		desc = !strings.EqualFold(descStr, "false")
 	}

 	ownerIDs := getOwnerIDs(c)
--- a/internal/handler/chat_session.go
+++ b/internal/handler/chat_session.go
@@ -19,9 +19,11 @@ package handler
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"net/http"
 	"ragflow/internal/common"
+	"strconv"
 	"strings"

 	"github.com/gin-gonic/gin"
@@ -67,13 +69,45 @@ func (h *ChatSessionHandler) ListChatSessions(c *gin.Context) {
 		return
 	}

+	// Mirror Python's list_sessions query handling: invalid/negative page
+	// values fall back to the default; page_size 0 yields an empty list and a
+	// negative page_size disables pagination.
+	page := 1
+	if pageStr := c.Query("page"); pageStr != "" {
+		if p, err := strconv.Atoi(pageStr); err == nil && p > 0 {
+			page = p
+		}
+	}
+	pageSize := 30
+	if pageSizeStr := c.Query("page_size"); pageSizeStr != "" {
+		if ps, err := strconv.Atoi(pageSizeStr); err == nil {
+			pageSize = ps
+		}
+	}
+
+	orderby := "create_time"
+	if queryOrderby := c.Query("orderby"); queryOrderby != "" {
+		switch queryOrderby {
+		case "create_time", "update_time", "name":
+			orderby = queryOrderby
+		default:
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("invalid orderby field: %s", queryOrderby))
+			return
+		}
+	}
+
+	desc := true
+	if descStr := c.Query("desc"); descStr != "" {
+		desc = !strings.EqualFold(descStr, "false")
+	}
+
 	// Call service to list chat sessions
 	ctx := c.Request.Context()
-	result, err := h.chatSessionService.ListChatSessions(ctx, userID, chatID)
+	result, err := h.chatSessionService.ListChatSessions(ctx, userID, chatID, c.Query("id"), c.Query("name"), orderby, desc, page, pageSize)
 	if err != nil {
-		// Check if it's an authorization error
-		if err.Error() == "Only owner of dialog authorized for this operation" {
-			common.ResponseWithHttpCodeData(c, http.StatusForbidden, 403, false, err.Error())
+		// Mirror Python: ownership failures return code 109 "No authorization."
+		if strings.Contains(err.Error(), "No authorization") {
+			common.ResponseWithCodeData(c, common.CodeAuthenticationError, false, "No authorization.")
 			return
 		}
 		common.ResponseWithHttpCodeData(c, http.StatusInternalServerError, 500, nil, err.Error())
@@ -231,6 +265,11 @@ func (h *ChatSessionHandler) ChatCompletions(c *gin.Context) {
 			false, nil,
 		)
 		if err != nil {
+			var codedErr *common.CodedError
+			if errors.As(err, &codedErr) {
+				common.ErrorWithCode(c, codedErr.Code, codedErr.Message)
+				return
+			}
 			common.ResponseWithHttpCodeData(c, http.StatusInternalServerError, 500, nil, err.Error())
 			return
 		}
@@ -282,7 +321,8 @@ func (h *ChatSessionHandler) CreateSession(c *gin.Context) {
 		if errors.Is(err, io.EOF) {
 			req = map[string]interface{}{}
 		} else {
-			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+			// Mirror Python's malformed-JSON contract message.
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Malformed JSON syntax: Missing commas/brackets or invalid encoding")
 			return
 		}
 	}
@@ -329,7 +369,8 @@ func (h *ChatSessionHandler) DeleteSessions(c *gin.Context) {
 		if errors.Is(err, io.EOF) {
 			req = map[string]interface{}{}
 		} else {
-			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+			// Mirror Python's malformed-JSON contract message.
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Malformed JSON syntax: Missing commas/brackets or invalid encoding")
 			return
 		}
 	}
@@ -361,20 +402,12 @@ func (h *ChatSessionHandler) UpdateSession(c *gin.Context) {
 	userID := user.ID
 	chatID, sessionID := c.Param("chat_id"), c.Param("session_id")

+	// An empty payload is a valid no-op (mirrors Python's update_session).
 	req := map[string]any{}
-	if err := c.ShouldBindJSON(&req); err != nil {
-		if errors.Is(err, io.EOF) {
-			common.ResponseWithCodeData(c, common.CodeArgumentError, nil,
-				"Request body cannot be empty")
-			return
-		}
+	if err := c.ShouldBindJSON(&req); err != nil && !errors.Is(err, io.EOF) {
 		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Invalid request: "+err.Error())
 		return
 	}
-	if len(req) == 0 {
-		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Request body cannot be empty")
-		return
-	}

 	ctx := c.Request.Context()
 	result, code, err := h.chatSessionService.UpdateSession(ctx, userID, chatID, sessionID, req)
--- a/internal/handler/chat_session_test.go
+++ b/internal/handler/chat_session_test.go
@@ -14,65 +14,6 @@ import (
 	"github.com/gin-gonic/gin"
 )

-func TestChatSessionHandlerUpdateSession_RejectsEmptyBody(t *testing.T) {
-	gin.SetMode(gin.TestMode)
-
-	recorder := httptest.NewRecorder()
-	ctx, _ := gin.CreateTestContext(recorder)
-	ctx.Request = httptest.NewRequest(http.MethodPatch, "/api/v1/chats/chat-1/sessions/session-1", nil)
-	ctx.Params = gin.Params{
-		{Key: "chat_id", Value: "chat-1"},
-		{Key: "session_id", Value: "session-1"},
-	}
-	ctx.Set("user", &entity.User{ID: "user-1"})
-
-	handler := NewChatSessionHandler(service.NewChatSessionService(), nil)
-	handler.UpdateSession(ctx)
-
-	if recorder.Code != http.StatusOK {
-		t.Fatalf("status=%d", recorder.Code)
-	}
-
-	var body map[string]interface{}
-	if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
-		t.Fatalf("decode response body: %v", err)
-	}
-	if got := body["code"]; got != float64(common.CodeArgumentError) {
-		t.Fatalf("code=%v", got)
-	}
-	if got := body["message"]; got != "Request body cannot be empty" {
-		t.Fatalf("message=%v", got)
-	}
-}
-
-func TestChatSessionHandlerUpdateSession_RejectsEmptyJSONObject(t *testing.T) {
-	gin.SetMode(gin.TestMode)
-
-	recorder := httptest.NewRecorder()
-	ctx, _ := gin.CreateTestContext(recorder)
-	ctx.Request = httptest.NewRequest(http.MethodPatch, "/api/v1/chats/chat-1/sessions/session-1", strings.NewReader(`{}`))
-	ctx.Request.Header.Set("Content-Type", "application/json")
-	ctx.Params = gin.Params{
-		{Key: "chat_id", Value: "chat-1"},
-		{Key: "session_id", Value: "session-1"},
-	}
-	ctx.Set("user", &entity.User{ID: "user-1"})
-
-	handler := NewChatSessionHandler(service.NewChatSessionService(), nil)
-	handler.UpdateSession(ctx)
-
-	var body map[string]interface{}
-	if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
-		t.Fatalf("decode response body: %v", err)
-	}
-	if got := body["code"]; got != float64(common.CodeArgumentError) {
-		t.Fatalf("code=%v", got)
-	}
-	if got := body["message"]; got != "Request body cannot be empty" {
-		t.Fatalf("message=%v", got)
-	}
-}
-
 func TestChatSessionHandlerUpdateMessageFeedback_RejectsEmptyBody(t *testing.T) {
 	gin.SetMode(gin.TestMode)

--- a/internal/handler/chunk.go
+++ b/internal/handler/chunk.go
@@ -720,17 +720,17 @@ func (h *ChunkHandler) AddChunk(c *gin.Context) {
 	}
 	importantKeywords, err := addChunkStringListField(rawBody, "important_keywords", "`important_keywords` is required to be a list", "`important_keywords` must be a list of strings")
 	if err != nil {
-		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
 	questions, err := addChunkStringListField(rawBody, "questions", "`questions` is required to be a list", "`questions` must be a list of strings")
 	if err != nil {
-		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
 	tagKwd, err := addChunkStringListField(rawBody, "tag_kwd", "`tag_kwd` is required to be a list", "`tag_kwd` must be a list of strings")
 	if err != nil {
-		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
 	imageBase64, err := addChunkStringPtrField(rawBody, "image_base64")
--- a/internal/handler/dataset.go
+++ b/internal/handler/dataset.go
@@ -88,28 +88,60 @@ func (h *DatasetsHandler) ListDatasets(c *gin.Context) {
 		return
 	}

+	// Mirror pydantic's extra="forbid" on ListDatasetReq.
+	for param := range c.Request.URL.Query() {
+		if !listDatasetsAllowedParams[param] {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Extra inputs are not permitted: %s", param))
+			return
+		}
+	}
+
+	// Mirror the pydantic validation of Python's ListDatasetReq.
 	page := 1
 	if pageStr := c.Query("page"); pageStr != "" {
-		if p, err := strconv.Atoi(pageStr); err == nil && p > 0 {
-			page = p
+		p, err := strconv.Atoi(pageStr)
+		if err != nil {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be a valid integer, unable to parse string as an integer")
+			return
 		}
+		if p < 1 {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be greater than or equal to 1")
+			return
+		}
+		page = p
 	}

 	pageSize := 30
 	if pageSizeStr := c.Query("page_size"); pageSizeStr != "" {
-		if ps, err := strconv.Atoi(pageSizeStr); err == nil && ps > 0 {
-			pageSize = ps
+		ps, err := strconv.Atoi(pageSizeStr)
+		if err != nil {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be a valid integer, unable to parse string as an integer")
+			return
 		}
+		if ps < 1 {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be greater than or equal to 1")
+			return
+		}
+		pageSize = ps
 	}

 	orderby := "create_time"
-	if queryOrderby := c.Query("orderby"); queryOrderby != "" {
+	if queryOrderby, exists := c.GetQuery("orderby"); exists {
+		if queryOrderby != "create_time" && queryOrderby != "update_time" {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be 'create_time' or 'update_time'")
+			return
+		}
 		orderby = queryOrderby
 	}

 	desc := true
 	if descStr := c.Query("desc"); descStr != "" {
-		desc = strings.ToLower(descStr) == "true"
+		parsed, ok := parsePythonBool(descStr)
+		if !ok {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Input should be a valid boolean, unable to interpret input")
+			return
+		}
+		desc = parsed
 	}

 	keywords := ""
@@ -128,6 +160,14 @@ func (h *DatasetsHandler) ListDatasets(c *gin.Context) {
 		ownerIDs = ext.OwnerIDs
 	}

+	// Mirror pydantic: a present-but-empty id fails UUID validation.
+	if rawID, exists := c.GetQuery("id"); exists {
+		if _, err := dataset.NormalizeDatasetID(strings.TrimSpace(rawID)); err != nil {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+			return
+		}
+	}
+
 	ctx := c.Request.Context()
 	data, total, code, err := h.datasetsService.ListDatasets(
 		ctx,
@@ -162,11 +202,21 @@ func (h *DatasetsHandler) CreateDataset(c *gin.Context) {
 		return
 	}

+	bodyBytes, _, ok := parseJSONRequestObject(c)
+	if !ok {
+		return
+	}
+
 	var req service.CreateDatasetRequest
-	if err := c.ShouldBindJSON(&req); err != nil {
+	if err := json.Unmarshal(bodyBytes, &req); err != nil {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
+	// Mirror Python's pydantic required validation.
+	if req.Name == "" || (len(bodyBytes) > 0 && jsonNullValue(bodyBytes, "name")) {
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, "Field validation for 'name' failed on the 'required' tag")
+		return
+	}

 	ctx := c.Request.Context()

@@ -200,6 +250,96 @@ func (h *DatasetsHandler) GetDataset(c *gin.Context) {
 }

 // UpdateDataset Update a dataset.
+// parsePythonBool mirrors pydantic's boolean coercion for query params:
+// accepts true/false/1/0/yes/no/y/n (case-insensitive).
+func parsePythonBool(s string) (bool, bool) {
+	switch strings.ToLower(s) {
+	case "true", "1", "yes", "y", "on":
+		return true, true
+	case "false", "0", "no", "n", "off":
+		return false, true
+	}
+	return false, false
+}
+
+// parseJSONRequestObject mirrors Python's validate_and_parse_json_request:
+// content-type check first, then JSON syntax, then object shape. On failure it
+// writes the error response and returns ok=false.
+func parseJSONRequestObject(c *gin.Context) (body []byte, raw map[string]interface{}, ok bool) {
+	if c.ContentType() != "application/json" {
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Unsupported content type: Expected application/json, got %s", c.GetHeader("Content-Type")))
+		return nil, nil, false
+	}
+
+	body, err := c.GetRawData()
+	if err != nil || len(body) == 0 {
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Malformed JSON syntax: Missing commas/brackets or invalid encoding")
+		return nil, nil, false
+	}
+
+	var payload interface{}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Malformed JSON syntax: Missing commas/brackets or invalid encoding")
+		return nil, nil, false
+	}
+	raw, isObject := payload.(map[string]interface{})
+	if !isObject {
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Invalid request payload: expected object, got %s", pythonJSONTypeName(payload)))
+		return nil, nil, false
+	}
+	return body, raw, true
+}
+
+// jsonNullValue checks if a field is explicitly null in the JSON body.
+func jsonNullValue(body []byte, field string) bool {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(body, &m); err != nil {
+		return false
+	}
+	raw, ok := m[field]
+	if !ok {
+		return false
+	}
+	return strings.TrimSpace(string(raw)) == "null"
+}
+
+// pythonJSONTypeName maps a decoded JSON value to the Python type name used in
+// the "Invalid request payload" contract message.
+func pythonJSONTypeName(v interface{}) string {
+	switch v.(type) {
+	case string:
+		return "str"
+	case []interface{}:
+		return "list"
+	case float64:
+		return "float"
+	case bool:
+		return "bool"
+	case nil:
+		return "NoneType"
+	default:
+		return "object"
+	}
+}
+
+// listDatasetsAllowedParams mirrors the query field set of Python's
+// ListDatasetReq (BaseListReq + include_parsing_status/ext; `type` is handled
+// before validation in the Python endpoint).
+var listDatasetsAllowedParams = map[string]bool{
+	"id": true, "name": true, "page": true, "page_size": true,
+	"orderby": true, "desc": true, "include_parsing_status": true,
+	"ext": true, "type": true,
+}
+
+// updateDatasetAllowedFields mirrors the field set of Python's UpdateDatasetReq
+// (CreateDatasetReq fields + dataset_id/pagerank/language/connectors).
+var updateDatasetAllowedFields = map[string]bool{
+	"name": true, "avatar": true, "description": true, "embedding_model": true,
+	"permission": true, "parse_type": true, "pipeline_id": true, "chunk_method": true,
+	"parser_id": true, "parser_config": true, "auto_metadata_config": true, "ext": true,
+	"dataset_id": true, "pagerank": true, "language": true, "connectors": true,
+}
+
 func (h *DatasetsHandler) UpdateDataset(c *gin.Context) {
 	user, errorCode, errorMessage := GetUser(c)
 	if errorCode != common.CodeSuccess {
@@ -218,15 +358,19 @@ func (h *DatasetsHandler) UpdateDataset(c *gin.Context) {
 		common.ResponseWithCodeData(c, common.CodeBadRequest, nil, "dataset id is required")
 		return
 	}
+	// Mirror the pydantic UUID validation of Python's UpdateDatasetReq.
+	if _, err := dataset.NormalizeDatasetID(datasetID); err != nil {
+		common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+		return
+	}

-	bodyBytes, err := c.GetRawData()
-	if err != nil {
-		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
+	bodyBytes, _, ok := parseJSONRequestObject(c)
+	if !ok {
 		return
 	}

 	var req service.UpdateDatasetRequest
-	if err = json.Unmarshal(bodyBytes, &req); err != nil {
+	if err := json.Unmarshal(bodyBytes, &req); err != nil {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
@@ -234,8 +378,15 @@ func (h *DatasetsHandler) UpdateDataset(c *gin.Context) {
 	// Detect an explicitly provided parser_config key (even {} or null) so it is not
 	// rejected as "no properties were modified", mirroring the Python contract.
 	var providedFields map[string]json.RawMessage
-	if err = json.Unmarshal(bodyBytes, &providedFields); err == nil {
+	if err := json.Unmarshal(bodyBytes, &providedFields); err == nil {
 		_, req.ParserConfigProvided = providedFields["parser_config"]
+		// Mirror pydantic's extra="forbid" on UpdateDatasetReq.
+		for field := range providedFields {
+			if !updateDatasetAllowedFields[field] {
+				common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Extra inputs are not permitted: %s", field))
+				return
+			}
+		}
 	}

 	ctx := c.Request.Context()
@@ -396,13 +547,40 @@ func (h *DatasetsHandler) DeleteDatasets(c *gin.Context) {
 		return
 	}

+	bodyBytes, rawPayload, ok := parseJSONRequestObject(c)
+	if !ok {
+		return
+	}
+
+	// Mirror pydantic's extra="forbid" on DeleteDatasetReq.
+	for field := range rawPayload {
+		if field != "ids" && field != "delete_all" {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Extra inputs are not permitted: %s", field))
+			return
+		}
+	}
+
 	var req struct {
 		IDs       *[]string `json:"ids"`
 		DeleteAll bool      `json:"delete_all,omitempty"`
 	}
-	if c.Request.ContentLength > 0 {
-		if err := c.ShouldBindJSON(&req); err != nil {
-			common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
+	if err := json.Unmarshal(bodyBytes, &req); err != nil {
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
+		return
+	}
+
+	// Mirror DeleteReq duplicate detection.
+	if req.IDs != nil {
+		seen := make(map[string]int, len(*req.IDs))
+		duplicates := make([]string, 0)
+		for _, id := range *req.IDs {
+			seen[id]++
+			if seen[id] == 2 {
+				duplicates = append(duplicates, id)
+			}
+		}
+		if len(duplicates) > 0 {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Duplicate ids: '%s'", strings.Join(duplicates, ", ")))
 			return
 		}
 	}
--- a/internal/handler/document.go
+++ b/internal/handler/document.go
@@ -31,6 +31,7 @@ import (
 	"ragflow/internal/common"
 	"ragflow/internal/entity"
 	"ragflow/internal/utility"
+	"reflect"
 	"strconv"
 	"strings"
 	"time"
@@ -392,13 +393,32 @@ func (h *DocumentHandler) DeleteDocuments(c *gin.Context) {
 		return
 	}

+	bodyBytes, _, ok := parseJSONRequestObject(c)
+	if !ok {
+		return
+	}
+
 	var req struct {
 		IDs       *[]string `json:"ids"`
 		DeleteAll bool      `json:"delete_all,omitempty"`
 	}
-	if c.Request.ContentLength > 0 {
-		if err := c.ShouldBindJSON(&req); err != nil {
-			common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
+	if err := json.Unmarshal(bodyBytes, &req); err != nil {
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
+		return
+	}
+
+	// Mirror pydantic's DeleteDocumentReq duplicate detection.
+	if req.IDs != nil {
+		seen := make(map[string]int, len(*req.IDs))
+		duplicates := make([]string, 0)
+		for _, id := range *req.IDs {
+			seen[id]++
+			if seen[id] == 2 {
+				duplicates = append(duplicates, id)
+			}
+		}
+		if len(duplicates) > 0 {
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Field: <ids> - Message: <Duplicate ids: '%s'> - Value: <%s>", strings.Join(duplicates, ", "), string(bodyBytes)))
 			return
 		}
 	}
@@ -505,6 +525,15 @@ func (h *DocumentHandler) ListDocuments(c *gin.Context) {

 	userID := c.GetString("user_id")

+	if orderby := c.Query("orderby"); orderby != "" {
+		switch orderby {
+		case "create_time", "update_time", "name":
+		default:
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("invalid orderby field: %s", orderby))
+			return
+		}
+	}
+
 	ctx := c.Request.Context()
 	if !h.datasetService.Accessible(ctx, datasetID, userID) {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, fmt.Sprintf("You don't own the dataset %s.", datasetID))
@@ -548,6 +577,30 @@ func (h *DocumentHandler) ListDocuments(c *gin.Context) {
 		return
 	}

+	// Mirror Python: an explicit id/name filter that matches nothing is an
+	// ownership error rather than an empty page. Each filter's existence is
+	// checked independently of the other.
+	if docID := c.Query("id"); docID != "" {
+		idOpts := opts
+		idOpts.DocIDs = []string{docID}
+		idOpts.Name = ""
+		_, idTotal, idErr := h.documentService.ListDocumentsByDatasetIDWithOptions(ctx, idOpts, 1, 1)
+		if idErr == nil && idTotal == 0 {
+			common.ResponseWithCodeData(c, common.CodeDataError, map[string]interface{}{"total": 0, "docs": []interface{}{}}, fmt.Sprintf("you don't own the document %s", docID))
+			return
+		}
+	}
+	if opts.Name != "" {
+		nameOpts := opts
+		nameOpts.DocIDs = nil
+		nameOpts.DocIDFilterApplied = false
+		_, nameTotal, nameErr := h.documentService.ListDocumentsByDatasetIDWithOptions(ctx, nameOpts, 1, 1)
+		if nameErr == nil && nameTotal == 0 {
+			common.ResponseWithCodeData(c, common.CodeDataError, map[string]interface{}{"total": 0, "docs": []interface{}{}}, fmt.Sprintf("you don't own the document %s", opts.Name))
+			return
+		}
+	}
+
 	docs := make([]map[string]interface{}, 0, len(documents))
 	for _, doc := range documents {
 		if opts.CreateTimeFrom > 0 && doc.CreateTime != nil && *doc.CreateTime < opts.CreateTimeFrom {
@@ -579,7 +632,7 @@ func parseDocumentListOptions(c *gin.Context, datasetID string) (dao.DocumentLis

 	opts.RunStatuses = normalizeRunStatusFilter(queryValues(c, "run", "run_status"))
 	if len(queryValues(c, "run", "run_status")) > 0 && len(opts.RunStatuses) == 0 {
-		return opts, "Invalid filter run status conditions"
+		return opts, fmt.Sprintf("Invalid filter run status conditions: %s", strings.Join(invalidRunStatuses(queryValues(c, "run", "run_status")), ", "))
 	}

 	opts.Name = c.Query("name")
@@ -615,6 +668,17 @@ func parseDocumentListOptions(c *gin.Context, datasetID string) (dao.DocumentLis
 }

 func (h *DocumentHandler) applyDocumentMetadataFilter(c *gin.Context, opts dao.DocumentListOptions) (dao.DocumentListOptions, string) {
+	// Mirror Python's metadata_condition query-param validation.
+	if raw := strings.TrimSpace(c.Query("metadata_condition")); raw != "" {
+		var mc interface{}
+		if err := json.Unmarshal([]byte(raw), &mc); err != nil {
+			return opts, fmt.Sprintf("metadata_condition must be valid JSON: %s.", raw)
+		}
+		if _, ok := mc.(map[string]interface{}); !ok {
+			return opts, "metadata_condition must be an object."
+		}
+	}
+
 	metadata, err := parseMetadataQuery(c.Request.URL.Query())
 	if err != nil {
 		return opts, err.Error()
@@ -820,6 +884,19 @@ func normalizeRunStatusFilter(statuses []string) []string {
 	return out
 }

+// invalidRunStatuses returns the raw filter values that do not map to a valid
+// run status, mirroring Python's "Invalid filter run status conditions: ...".
+func invalidRunStatuses(statuses []string) []string {
+	valid := map[string]bool{"UNSTART": true, "RUNNING": true, "CANCEL": true, "DONE": true, "FAIL": true}
+	invalid := make([]string, 0)
+	for _, status := range statuses {
+		if !valid[strings.ToUpper(status)] {
+			invalid = append(invalid, status)
+		}
+	}
+	return invalid
+}
+
 func (h *DocumentHandler) UploadDocuments(c *gin.Context) {
 	user, errorCode, errorMessage := GetUser(c)
 	if errorCode != common.CodeSuccess {
@@ -1421,8 +1498,22 @@ func (h *DocumentHandler) StartIngestionTask(c *gin.Context) {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, "`document_ids` is required")
 		return
 	}
+	// Gin's `required` accepts an empty non-nil slice; reject it explicitly.
+	if len(req.DocumentIDs) == 0 {
+		common.ResponseWithCodeData(c, common.CodeDataError, nil, "`document_ids` is required")
+		return
+	}

 	userID := c.GetString("user_id")
+	if orderby := c.Query("orderby"); orderby != "" {
+		switch orderby {
+		case "create_time", "update_time", "name":
+		default:
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("invalid orderby field: %s", orderby))
+			return
+		}
+	}
+
 	ctx := c.Request.Context()
 	if !h.datasetService.Accessible(ctx, datasetID, userID) {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, fmt.Sprintf("You don't own the dataset %s.", datasetID))
@@ -1529,16 +1620,25 @@ func (h *DocumentHandler) StopParseDocuments(c *gin.Context) {

 	var req StopParseDocumentRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		common.ErrorWithCode(c, common.CodeBadRequest, err.Error())
+		common.ErrorWithCode(c, common.CodeDataError, "`document_ids` is required")
 		return
 	}

 	if len(req.DocumentIDs) == 0 {
-		common.ErrorWithCode(c, common.CodeBadRequest, "`document_ids` is required")
+		common.ErrorWithCode(c, common.CodeDataError, "`document_ids` is required")
 		return
 	}

 	userID := c.GetString("user_id")
+	if orderby := c.Query("orderby"); orderby != "" {
+		switch orderby {
+		case "create_time", "update_time", "name":
+		default:
+			common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("invalid orderby field: %s", orderby))
+			return
+		}
+	}
+
 	ctx := c.Request.Context()
 	if !h.datasetService.Accessible(ctx, datasetID, userID) {
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, fmt.Sprintf("You don't own the dataset %s.", datasetID))
@@ -1619,6 +1719,25 @@ func (h *DocumentHandler) UpdateDatasetDocument(c *gin.Context) {
 	}
 	var req document.UpdateDatasetDocumentRequest
 	if err = json.Unmarshal(body, &req); err != nil {
+		// Mirror pydantic's "Field: <f> - Message: <m> - Value: <v>" format.
+		var typeErr *json.UnmarshalTypeError
+		if errors.As(err, &typeErr) {
+			value := typeErr.Value
+			if rawValue, ok := raw[typeErr.Field]; ok {
+				// Render scalars the way Python's str() does: strings
+				// unquoted, other JSON values verbatim.
+				var scalar interface{}
+				if jsonErr := json.Unmarshal(rawValue, &scalar); jsonErr == nil {
+					if str, isStr := scalar.(string); isStr {
+						value = str
+					} else {
+						value = string(rawValue)
+					}
+				}
+			}
+			common.ResponseWithCodeData(c, common.CodeDataError, nil, fmt.Sprintf("Field: <%s> - Message: <Input should be a valid %s> - Value: <%s>", typeErr.Field, pythonJSONKindName(typeErr), value))
+			return
+		}
 		common.ResponseWithCodeData(c, common.CodeDataError, nil, err.Error())
 		return
 	}
@@ -1845,3 +1964,26 @@ func parseMetadataDeletes(raw interface{}) ([]document.DocumentMetadataDelete, s
 	}
 	return deletes, ""
 }
+
+// pythonJSONKindName maps a JSON unmarshal type error to the pydantic type
+// name used in the "Input should be a valid ..." contract message.
+func pythonJSONKindName(typeErr *json.UnmarshalTypeError) string {
+	if typeErr.Type == nil {
+		return "value"
+	}
+	switch typeErr.Type.Kind() {
+	case reflect.String:
+		return "string"
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return "integer"
+	case reflect.Float32, reflect.Float64:
+		return "number"
+	case reflect.Bool:
+		return "boolean"
+	case reflect.Slice, reflect.Array:
+		return "list"
+	case reflect.Map:
+		return "dictionary"
+	}
+	return "value"
+}
--- a/internal/handler/search.go
+++ b/internal/handler/search.go
@@ -334,7 +334,7 @@ func (h *SearchHandler) UpdateSearch(c *gin.Context) {
 		errMsg := err.Error()
 		switch errMsg {
 		case "no authorization":
-			common.ResponseWithCodeData(c, common.CodeAuthenticationError, false, "no authorization")
+			common.ResponseWithCodeData(c, common.CodeAuthenticationError, false, "No authorization.")
 		case "duplicated search name":
 			common.ResponseWithCodeData(c, common.CodeDataError, nil, "Duplicated search name.")
 		default:
--- a/internal/handler/searchbot.go
+++ b/internal/handler/searchbot.go
@@ -89,8 +89,10 @@ func (r *SearchBotRetrievalTestRequest) UnmarshalJSON(data []byte) error {
 }

 // SearchBotRequest is the request body for POST /api/v1/searchbots/related_questions.
+// Question is validated manually below so the error message follows the
+// established API contract instead of the Gin validator format.
 type SearchBotRequest struct {
-	Question string `json:"question" binding:"required"`
+	Question string `json:"question"`
 	SearchID string `json:"search_id,omitempty"`
 }

--- a/internal/handler/tenant.go
+++ b/internal/handler/tenant.go
@@ -456,6 +456,14 @@ func (h *TenantHandler) InsertMetadataFromFile(c *gin.Context) {
 	// Use user.ID as tenant ID (user IS the tenant in user mode)
 	tenantID := user.ID

+	// Ensure the metadata store exists before writing (service-layer
+	// create-on-first-write logic; the engine layer assumes it exists).
+	metadataSvc := service.NewMetadataService()
+	if err := metadataSvc.EnsureMetadataStore(c.Request.Context(), tenantID); err != nil {
+		common.ResponseWithHttpCodeData(c, http.StatusBadRequest, 400, nil, "failed to ensure metadata store: "+err.Error())
+		return
+	}
+
 	// Get the document engine and insert
 	docEngine := engine.Get()
 	result, err := docEngine.InsertMetadata(c.Request.Context(), inputFormat.Chunks, tenantID)