Refactor types for better readability

**Problem**
When working with api, the error messages could be more descriptive.

**Suggestion**
Improve error handling and add detailed error messages.

**Context**
This would help with debugging and maintenance.

The issue does not name files, tests, or an entry point. Start by locating the API error-handling paths in the Shell project and review how current errors are constructed. Done means the relevant API failures have clearer, more descriptive messages and the existing checks still pass.

Written by the indexing model from the issue text.