feat(backend): improve status and error contract consistency (#406)

## Summary

This PR standardizes backend error handling so malformed or invalid
client queries return predictable HTTP responses instead of generic `500
Internal Server Error` results.

It aligns runtime status mapping, structured error payloads, and OpenAPI
documentation to provide a clearer and more reliable contract for API
consumers.

---

## Related Issue

Fixes #405

---

## Notes

This is a backend API contract improvement focused on better HTTP
semantics, stronger documentation, and safer client-facing error
handling.

Author: SaitejaKommi

app/_types.py

@@ -90,6 +90,7 @@ class SearchResponseDebug(BaseModel):
 class SearchResponseError(BaseModel):
     title: str
     description: str | None = None
+    status: int | None = None
 
 
 class ErrorSearchResponse(BaseModel):

app/api.py

@@ -18,6 +18,7 @@
     PostSearchParameters,
     SearchResponse,
     SuccessSearchResponse,
+    ErrorSearchResponse,
 )
 from app.config import settings
 from app.postprocessing import process_taxonomy_completion_response
@@ -101,12 +102,14 @@ def get_document(
 def status_for_response(result: SearchResponse):
     if isinstance(result, SuccessSearchResponse):
         return status.HTTP_200_OK
+    elif isinstance(result, ErrorSearchResponse) and result.errors:
+        # returns the status of the first error
+        return result.errors[0].status or status.HTTP_500_INTERNAL_SERVER_ERROR
     else:
-        # TODO: should we refine that ?
         return status.HTTP_500_INTERNAL_SERVER_ERROR
 
 
-@app.post("/search")
+@app.post("/search", responses={400: {"model": ErrorSearchResponse}, 500: {"model": ErrorSearchResponse}})
 def search(
     response: Response, search_parameters: Annotated[PostSearchParameters, Body()]
 ) -> SearchResponse:
@@ -121,7 +124,7 @@ def search(
     return result
 
 
-@app.get("/search")
+@app.get("/search", responses={400: {"model": ErrorSearchResponse}, 500: {"model": ErrorSearchResponse}})
 def search_get(
     response: Response, search_parameters: Annotated[GetSearchParameters, Query()]
 ) -> SearchResponse:

app/search.py

@@ -92,7 +92,7 @@ def search(
     except QueryCheckError as e:
         return ErrorSearchResponse(
             debug=SearchResponseDebug(),
-            errors=[SearchResponseError(title="QueryCheckError", description=str(e))],
+            errors=[SearchResponseError(title="QueryCheckError", description=str(e), status=400)],
         )
     (
         logger.debug(