Implementation:Mlc ai Mlc llm Error Protocol

Overview

The Error Protocol module defines error handling structures and utilities for the MLC LLM serving layer. Located at python/mlc_llm/protocol/error_protocol.py (35 lines), it provides a custom exception class, an error response model, and helper functions for converting exceptions into JSON error responses compatible with FastAPI.

Purpose

This module standardizes how errors are represented and returned in the MLC LLM REST API. It provides:

• A custom BadRequestError exception for invalid engine requests
• A Pydantic-based ErrorResponse model for structured error JSON payloads
• A factory function create_error_response for building JSON responses from HTTP status codes
• An async exception handler that integrates with FastAPI's exception handling system

Key Components

BadRequestError Class

A custom exception extending Python's built-in ValueError, used to signal bad requests within the engine layer:

class BadRequestError(ValueError):
    """The exception for bad requests in engines."""

    def __init__(self, *args: object) -> None:
        super().__init__(*args)

This exception is intended to be raised in engine code and caught by the FastAPI exception handler registered for this type.

ErrorResponse Class

A Pydantic BaseModel representing the JSON structure of an error response:

class ErrorResponse(BaseModel):
    object: str = "error"
    message: str
    code: Optional[int] = None

Field	Type	Default	Description
object	str	"error"	Object type identifier, always "error"
message	str	(required)	Human-readable error description
code	Optional[int]	None	Optional HTTP status code

create_error_response Function

A factory function that constructs a FastAPI JSONResponse from an HTTP status code and error message:

def create_error_response(status_code: HTTPStatus, message: str) -> fastapi.responses.JSONResponse:
    return fastapi.responses.JSONResponse(
        ErrorResponse(message=message, code=status_code.value).model_dump_json(by_alias=True),
        status_code=status_code.value,
    )

The response body is serialized using Pydantic's model_dump_json with by_alias=True to respect any field aliases.

bad_request_error_handler Function

An async exception handler designed to be registered with FastAPI to automatically convert BadRequestError exceptions into proper HTTP 400 responses:

async def bad_request_error_handler(_request: fastapi.Request, e: BadRequestError):
    return create_error_response(status_code=HTTPStatus.BAD_REQUEST, message=e.args[0])

This handler extracts the first argument from the exception (the error message) and wraps it in a JSON response with HTTP status 400 (Bad Request).

Usage Pattern

In the MLC LLM serving infrastructure, this module is typically used as follows:

1. Engine code raises BadRequestError when a request is invalid
2. The FastAPI application registers bad_request_error_handler as an exception handler for BadRequestError
3. The handler intercepts the exception and returns a structured JSON error response to the client

Dependencies

• http.HTTPStatus -- Standard library HTTP status codes
• fastapi -- For Request, responses.JSONResponse
• pydantic -- For BaseModel data validation

File Location

python/mlc_llm/protocol/error_protocol.py