Improve backend status/error contract consistency

[SaitejaKommi]

Description

The backend API currently maps validation and query-check failures (such as QueryCheckError) into an ErrorSearchResponse structure, which provides a consistent payload shape.

However, the HTTP status behavior is not equally structured. Outside of SuccessSearchResponse, the router may fall back to broad hardcoded responses such as 500 Internal Server Error, even for client-originated validation issues.

In addition, generated OpenAPI documentation does not clearly advertise that search endpoints may return ErrorSearchResponse, which can leave generated clients unaware of available error payload contracts.

This issue proposes aligning runtime status codes, response models, and API documentation into a consistent typed contract.

---

Affected Areas

• Search API routers (GET / POST)
• Error response models
• OpenAPI schema generation
• Query validation / exception handling flow

---

Current Behavior

• ErrorSearchResponse exists as a payload model.
• Router status handling may be overly generic.
• Validation/query parse errors may surface as 500 instead of client errors.
• OpenAPI docs may omit explicit error response schemas.
• Generated API clients may miss structured error contracts.

---

Expected Behavior

• Error payloads should map to semantically correct HTTP status codes.
• Client-caused validation errors should return 400 Bad Request.
• Search endpoints should document structured error responses in OpenAPI.
• Generated clients should understand both success and error contracts.

---

Proposed Solution

Typed Status Mapping

Expose an integer .status (or equivalent structured status metadata) through ErrorSearchResponse / related Pydantic models.

Better Validation Error Semantics

Map query validation / parsing issues such as:

• QueryCheckError
• Luqum parsing / syntax exceptions
• Invalid query parameters

to:

• 400 Bad Request

Router Response Documentation

Extend @app.get / @app.post route definitions with explicit responses= metadata so OpenAPI includes:

• Success response model(s)
• Structured error response model(s)
• Appropriate status codes

---

Impact

• Better HTTP semantics
• Improved client developer experience
• Stronger generated SDK compatibility
• Easier debugging for consumers
• No breaking success-response behavior intended

---

Testing

• Ensure backend unit tests pass.
• Verify validation errors return 400.
• Confirm unexpected server errors still return 500.
• Validate OpenAPI docs include error schemas.
• Test generated clients can see documented error models.

---

Additional Context

This is an API contract quality improvement focused on consistency between payload models, HTTP statuses, and documentation.