{"record":{"id":"62f5106605fae001","repo":"infiniflow/ragflow","slug":"page-size-must-be-less-than-or-equal-to-rest-api","errorCode":null,"errorMessage":"page_size must be less than or equal to {REST_API_MAX_PAGE_SIZE}","messagePattern":"page_size must be less than or equal to (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"api/utils/pagination_utils.py","lineNumber":43,"sourceCode":"    try:\n        int_page = int(page)\n    except (TypeError, ValueError):\n        return DEFAULT_PAGE\n    if int_page < 1:\n        return DEFAULT_PAGE\n    return int_page\n\n\ndef validate_rest_api_page_size(page_size) -> int:\n    \"\"\"Validate page_size, if invalid, silent fallback to default page_size, and validate it against the public maximum.\"\"\"\n    try:\n        int_page_size = int(page_size)\n    except (TypeError, ValueError):\n        return DEFAULT_PAGE_SIZE\n    if int_page_size < 1:\n        return DEFAULT_PAGE_SIZE\n    if int_page_size > REST_API_MAX_PAGE_SIZE:\n        raise ValueError(f\"page_size must be less than or equal to {REST_API_MAX_PAGE_SIZE}\")\n    return int_page_size\n\n\ndef validate_rest_api_ids(ids: list | None, field_name: str = \"ids\") -> list | None:\n    \"\"\"Validate REST API ID lists against the public maximum.\"\"\"\n    if ids is not None and len(ids) > REST_API_MAX_IDS:\n        raise ValueError(f\"{field_name} must contain at most {REST_API_MAX_IDS} IDs\")\n    return ids\n","sourceCodeStart":25,"sourceCodeEnd":52,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/api/utils/pagination_utils.py#L25-L52","documentation":"Raised by validate_rest_api_page_size when the requested page_size exceeds REST_API_MAX_PAGE_SIZE (100). Values that are non-numeric or < 1 silently fall back to DEFAULT_PAGE_SIZE (30), but an explicit oversized value is rejected with ValueError to prevent unbounded result sets.","triggerScenarios":"Calling a paginated REST API (dataset/document/chat listings) with ?page_size=101 or larger; SDK or MCP clients ported from internal endpoints that allowed bigger pages.","commonSituations":"Clients raising page_size to reduce round-trips; porting pagination params from v0 SDK defaults; scripts iterating large datasets with naive page-size math.","solutions":["Cap page_size at 100 in the client and paginate with increasing page numbers instead.","If you legitimately need more rows per call, use filter/ids narrowing or the bulk endpoints rather than a huge page_size.","Handle the ValueError (typically surfaced as 400) by clamping to the max and retrying."],"exampleFix":"# before\nresp = sdk.list_documents(kb_id, page_size=500)  # ValueError\n\n# after\npage_size = min(requested, 100)\nresp = sdk.list_documents(kb_id, page_size=page_size, page=page)","handlingStrategy":"validation","validationCode":"page_size = min(int(page_size or 30), 100)  # clamp before the call\nresp = sdk.list_documents(kb_id, page=page, page_size=page_size)","typeGuard":"def is_valid_page_size(page_size: int) -> bool:\n    return isinstance(page_size, int) and 1 <= page_size <= 100","tryCatchPattern":"try:\n    resp = list_endpoint(page=page, page_size=page_size)\nexcept ValueError as e:\n    if 'page_size' in str(e):\n        resp = list_endpoint(page=page, page_size=100)\n    else:\n        raise","preventionTips":["Clamp page_size to 100 (REST_API_MAX_PAGE_SIZE) in all clients and SDKs.","Use page-number iteration instead of oversized pages for large result sets.","Remember invalid/low values silently become 30 (DEFAULT_PAGE_SIZE); only over-limit values raise."],"tags":["validation","pagination","rest-api","limit","page-size"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}