fix(api): return 422 for out-of-range pagination query values - #15223

Changes

custom_params declared page/size as unbounded Query(None) and then passed them to fastapi_pagination.Params, which validates size as ge=1, le=100 itself. So an out-of-range value raised ValidationError during dependency resolution — before the handler, which puts it past the route's own try/except and into the app-wide Exception handler in main.py, answering 500 with the internal validation text echoed to the client.

This declares the same bounds on the query parameters so FastAPI rejects them as 422, matching the sibling routes that already depend on Params directly.

Fixes #15222

Affected routes: /api/v1/monitor/transactions, /api/v1/projects/{project_id}, /api/v1/folders/{folder_id}.

Nothing that works today changes: None for both parameters still means "unpaginated", size=100 is still the ceiling, and ?page=3 still defaults size to MAX_PAGE_SIZE. page=0 / size=0 now return 422 instead of being silently rewritten to the defaults.

How was this tested

src/backend/tests/unit/api/test_api_utils.py — a minimal FastAPI() app whose only dependency is custom_params, so no database, no network, no service setup:

• 5 out-of-range cases assert 422 (3 that used to be 500, 2 that used to be a silently rewritten 200)
• 5 accepted cases assert the same 200 payloads as before, including "no query parameters at all"
• 1 drift guard pins MAX_PARAMS_PAGE_SIZE/MIN_PAGE_SIZE against the bounds Params itself carries, because the bounds are now declared in two places

Measured locally on main @ 5621dcfd (Python 3.12, uv, Windows):

# new tests, original unbounded declarations kept:  5 failed, 6 passed
#   assert 500 == 422  (size=101, size=1000, size=-5)
#   assert 200 == 422  (size=0, page=0)
# new tests, with this commit:                     11 passed
# whole module (uv run pytest src/backend/tests/unit/api/test_api_utils.py): 28 passed
# uv run ruff format --diff <both files> -> 2 files already formatted
# uv run ruff check <both files>         -> All checks passed!

make format_backend / make unit_tests were not run — make is not available on this machine, so the uv run equivalents above are what actually executed. Importing and building the monitor, projects and folders routers was also checked, because FastAPI validates a Query bound at route-build time: all three still build (this is what caught an earlier version of the fix that put the None default inside Annotated, which FastAPI rejects).

What else to consider

• The 500 also leaked the raw validation string. It is not sensitive in this case, but if the team wants a consistent error envelope, the app-wide handler could stop echoing str(exc) — out of scope here.
• MAX_PAGE_SIZE = 50 is still only a default, not a bound, so the accepted ceiling stays 100 (what Params allows). Tightening it to 50 would turn currently-working size=51..100 requests into 422s, so I deliberately left it alone.
• MIN_PAGE_SIZE is reused as the ge for both parameters; it already equals the ge=1 that Params puts on page.

Attribution: this change was prepared by an AI coding agent working from the account holder's instruction, and has not been reviewed by a human before opening. The RED/GREEN numbers above are measured output, not estimates.

Summary by CodeRabbit

• Bug Fixes
  • Invalid pagination values are now rejected with a clear HTTP 422 response instead of causing a server error.
  • Pagination parameters enforce valid minimum values, with page sizes capped at 100.
  • Valid pagination values continue to be accepted and processed as expected.