[FEATURE] Add Custom Library-Specific Exceptions for Improved Error Handling in Dependent Projects

[Maxitosh]

Description

Currently, PyTonLib uses generic Python exceptions, making it challenging for dependent projects, such as ton-http-api, to handle specific error cases reliably. This limitation requires dependent projects to rely on error messages, which are neither robust nor maintainable.

Why?

An unhandled exception in ton-http-api results in a default HTTP response with a 503 status code, which doesn’t always reflect the nature of the error. To produce appropriate HTTP responses, it’s essential to detect the specific errors originating from PyTONLib reliably.

For example, when calling /getTokenData with an address that isn’t a Jetton or NFT (e.g. UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ), the endpoint currently returns a 503 error. A more suitable response would be a 422 status code, indicating an unprocessable request. However, it’s challenging to catch and handle this case effectively without custom exceptions.

Proposed Solution

Introduce a custom base exception class and create specific exceptions that inherit from this base.

This change lays the foundation for more expressive error handling in PyTONLib and helps make dependent applications, like ton-http-api, more resilient and user-friendly.

#68