refactor(exceptions): MinimaxRequestError is a subclass of MinimaxAPIError, conflating two error categories

minimax_mcp/exceptions.py から始めて現在の例外階層を確認し、その後 minimax_mcp/server.py の MinimaxAPIError ハンドラーを確認します。issue で説明されている中立的なベースアプローチを選択し、API と request の異なるカテゴリを維持したうえで、既存の PR #87 のテストが意図した例外動作で引き続きパスすることを検証します。

Summary

In minimax_mcp/exceptions.py:

class MinimaxAPIError(Exception):
    """Base exception for Minimax API errors."""
    pass

class MinimaxRequestError(MinimaxAPIError):
    """Request related errors."""
    pass

MinimaxRequestError is a subclass of MinimaxAPIError, but the two represent different error categories:

• MinimaxAPIError — problems talking to the remote API (auth, network, 5xx, etc.). Worth retrying.
• MinimaxRequestError — client-side problems (missing required field, bad combination, etc.). Never worth retrying.

Because of the inheritance, every except MinimaxAPIError block in minimax_mcp/server.py also catches MinimaxRequestError. This makes it impossible for callers to handle "transient" vs "permanent" failures differently — and it complicates retry logic, metrics, and error budgets.

Impact

• All tool functions return the same generic error message format for both transient and permanent failures, even though clients might want to retry one and not the other.
• The PR #87 test suite had to be written around the inheritance — e.g. with pytest.raises(MinimaxRequestError) works, but a hypothetical try/except MinimaxAPIError: retry() would also catch MinimaxRequestError, which is the wrong behavior.

Suggested fix

Two options, in order of preference:

1. Make them siblings under MinimaxError (rename the current base to MinimaxError or add a new neutral base). Both MinimaxAPIError and MinimaxRequestError should be siblings, not parent/child.
2. At minimum, update existing except MinimaxAPIError as e: blocks to except (MinimaxAPIError, MinimaxRequestError) as e: (or except MinimaxError as e: after the refactor) and document the categories in each tool's docstring.

Option 1 is cleaner and a one-file change.

Discovered via

Issue filed as a follow-up to PR #87 (test coverage). Tests pass either way, but the inheritance makes the error-handling story confusing for new contributors.

🤖 Generated with Claude Code