feat: structured error handling and input validation for upload API

[Krushna-Pisal]

Summary

This PR introduces structured error responses and improves input validation in the upload API.

Problem

Currently, error responses in the upload endpoint are unstructured and inconsistent, making it difficult to handle errors reliably on the client side. Additionally, invalid inputs (such as malformed source URLs) can lead to unexpected failures during processing.

Solution

• Introduced a reusable error handler utility (helpers/error_handler.py) for consistent error responses

• Standardized error response format with:

  • code (machine-readable)
  • message (user-friendly)
  • retryable flag
  • optional details

• Updated key error cases in /api/upload to use the new structured format

• Added input validation for srcUrl to prevent invalid requests before processing

Example Response

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid source URL provided",
    "retryable": false
  }
}

Benefits

• Improves API consistency and readability
• Enables better client-side error handling
• Prevents crashes due to invalid input
• Enhances overall reliability of the upload flow

Scope

Changes are currently applied to the upload endpoint. The same structure can be extended to other APIs in future for consistency.

Notes

• This PR focuses on minimal, targeted improvements without altering existing functionality.
• Designed to be backward-compatible and easily extendable.