feat(backend): improve status and error contract consistency

[SaitejaKommi]

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

---

What Changed

Enhanced Error Response Schema

Updated SearchResponseError / ErrorSearchResponse to include:

status: int

This enables payload-level status semantics alongside HTTP responses.

Refined Status Mapping Logic

Improved status_for_response behavior in api.py to:

• Derive HTTP status codes from structured response models
• Use 500 only for unspecified/unexpected failures
• Centralize response-status business logic

Improved Validation Error Handling

Wrapped query validation exceptions such as QueryCheckError into structured client errors returning:

• 400 Bad Request

This prevents malformed queries from surfacing as server faults.

OpenAPI Contract Improvements

Added explicit route response mappings such as:

responses={
  400: {"model": ErrorSearchResponse},
  ...
}

to FastAPI decorators for documented success/error contracts.

---

Affected Files

• api.py
• search.py
• Response model definitions
• FastAPI route declarations

---

Testing

Verification gateway executed successfully:

• Backend unit tests ✅
• Backend integration tests ✅
• Frontend build/tests (dev) ✅
• Frontend build/tests (prod) ✅

---

Notes

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