Improve Error Handling Documentation

[jeffsawatzky]

Enhancement

It isn't clear to me, based on the documention, what kind of error should be raised in certain situations.
For reference I am currently on FastMCP v3.4.8

For additional context, we were originally raising a ToolError for everything (authorization errors, validation errors, entity not found, actual server errors, etc).

These ToolErrors have been surfacing in DataDog and the Claude dashboard as server errors. However, some of these are client side issues (authorization, validation, entity not found) and shouldn't be surfacing as server errors.

I was poking around in the FastMCP code, and saw this bit here:

try:
    return await tool._run(arguments or {}, task_meta=task_meta)
except ValidationError as e:
    # Argument-validation failure (a bad call). FunctionTool
    # converts pydantic's call-validation error into fastmcp's
    # ValidationError (see #4128) so it can be filtered as a
    # client error. Log the underlying detail without a URL or
    # traceback, matching the previous pydantic-error logging.
    cause = e.__cause__
    detail = (
        cause.errors(include_url=False)
        if isinstance(cause, PydanticValidationError)
        else str(e)
    )
    logger.warning("Invalid arguments for tool %r: %s", name, detail)
    raise

So I figured we should be raising ValidationError instead of ToolError for our own validations.

And looking at exceptions.py I see additional errors that can be used:

• ValidationError
• ToolError
• AuthorizationError
• NotFoundError

And based on that, here are my assumptions:

• We should raise AuthorizationError from our custom authorization middleware
• We should raise ValidationError when we have custom validations that fail (for example, if a tool has two parameters, date1 and date2 and we have a validation that date1<date2)
• We should raise NotFoundError when the model passes in a non-existant entity id to a get_entity(id:int) type of tool
• We should raise ToolError for actual server errors

Are these assumptions correct?

I have already update the validation to raise ValidationError instead of ToolError and they are still surfacing as a server error.

I looked into the ErrorHandlingMiddleware, but this doesn't seem to help we either because of the following:

• It has no special handling of ToolError, AuthenticationError, ValidationError or any of the other FastMCP errors other than NotFoundError, so it doesn't help me here.
• It converts standard python errors into certain errors which may not alwasy be correct. For example, it converts ValueError and TypeError into an "invalid params" response, which isn't always acceptable as these could be a bug in the code and be an actual server error.

Is it possible to have documentation on the best way to deal with client side errors? Maybe this exists somewhere, but I haven't been able to find it. And currently, it seems like no matter which error I raise (ToolError, ValidationError, etc) they are all surfaced as server errors in DataDog and Claude's dashboard.

I have also asked in the Discord community here.