Allow solvers to return custom errors

[ashleychandy]

Description

Fixes #4222

Previously, when solvers couldn't compute quotes for RWA tokens, they returned a generic QuotingFailed error. This made it difficult for the frontend to provide helpful feedback.

This change adds support for custom solver errors that can be returned when quoting fails. Solvers can now indicate specific reasons like:

• TradingOutsideAllowedWindow
• TokenTemporarilySuspended
• InsufficientLiquidity
• UnauthorizedTrader
• Other

When a solver returns a custom error, the driver propagates it through the API response so the frontend can display an appropriate error message.

Changes

• Added SolverError enum with 5 variants in solvers-dto
• Added optional error field to Solutions DTO
• Updated driver to detect and propagate custom solver errors
• Added 5 new error kinds to the API error handler
• Updated observability to track SolverCustomError metric
• Updated mock solver in e2e tests

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[ashleychandy]

I have read the CLA Document and I hereby sign the CLA

[gemini-code-assist]

Code Review

This pull request introduces a mechanism for solvers to return custom errors, which are then propagated to the API. This is a valuable improvement for providing more specific feedback to users. The implementation is solid, with changes across the DTOs, driver, and observability components. I've identified one area in the error handling logic where code duplication can be reduced to improve maintainability.

[gemini-code-assist]

This match statement contains significant code duplication for handling the optional message and providing a default description. This can be refactored to reduce complexity and improve maintainability by separating the logic for identifying the error type from the logic for constructing the description string.

                let (kind, message, default_description) = match custom_err {
                    solvers_dto::solution::SolverError::TradingOutsideAllowedWindow { message } => (
                        Kind::TradingOutsideAllowedWindow,
                        message,
                        "Token can only be traded during specific time windows",
                    ),
                    solvers_dto::solution::SolverError::TokenTemporarilySuspended { message } => (
                        Kind::TokenTemporarilySuspended,
                        message,
                        "Token is temporarily suspended from trading",
                    ),
                    solvers_dto::solution::SolverError::InsufficientLiquidity { message } => (
                        Kind::InsufficientLiquidity,
                        message,
                        "Insufficient liquidity for the requested trade size",
                    ),
                    solvers_dto::solution::SolverError::UnauthorizedTrader { message } => (
                        Kind::UnauthorizedTrader,
                        message,
                        "Token requires special permissions or whitelisting",
                    ),
                    solvers_dto::solution::SolverError::Other { message } => (
                        Kind::CustomSolverError,
                        message,
                        "Solver returned a custom error",
                    ),
                };
                let description = message.as_deref().unwrap_or(default_description).to_string();
                return (
                    axum::http::StatusCode::BAD_REQUEST,
                    axum::Json(Error { kind, description }),
                );

[jmg-duarte]

This should probably be it's own function

[jmg-duarte]

All message fields are optional, that hints that the modelling is not quite there

[jmg-duarte]

From the code alone I don't see how this change modifies anything in the rest of the code

[jmg-duarte]

If the solution is the payload the solver currently returns, adding an error field is a bit confusing as it's no longer a solution

Feels to me that an enum would be better suited (names up for discussion)

enum SolverResponse { Solution { solutions: Vec<Solution> }, Error { code: SolverError, message: Option<String> }

Separating the message from the code also brings more flexibility

[ashleychandy]

Thanks for the review! Implemented the changes you suggested - separated error code from message, refactored SolverResponse to a proper enum, and simplified the error mapping.