Standard Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• packages/utils/spec/errors.md
• packages/utils/test/errors.test.ts
• apps/api/test/infrastructure/http/error-handler.test.ts
• apps/api/test/infrastructure/http/server.integration.test.ts
• apps/api/spec/bio.md
• apps/api/test/modules/bio/interface/bio.tool.integration.test.ts

Standard error handling in the thoth project provides a unified mechanism for managing domain and infrastructure errors across all modules. It utilizes a base AppError class and specialized HTTP subclasses to ensure consistent error reporting, status codes, and JSON response formats across the API and MCP (Model Context Protocol) layers.

Architecture and Core Classes

The error handling system centers on the AppError class located in the utils package. This class serves as the base for all domain-specific errors and carries essential metadata including an ErrorCode, an HTTP status code, a descriptive message, and optional fieldErrors for validation failures.

The diagram shows the class hierarchy where specialized HTTP errors inherit from the base AppError class.
Sources: packages/utils/spec/errors.md:1-20, packages/utils/test/errors.test.ts:10-50

HTTP Error Mapping

Specific subclasses lock their HTTP status codes to maintain RESTful standards:

Class	HTTP Status	Description
BadRequest	400	The request is malformed or contains illegal arguments.
Unauthorized	401	The request requires authentication but lacks valid credentials.
Forbidden	403	The authenticated user lacks permission for the resource.
NotFound	404	The requested resource could not be found.
Conflict	409	The request conflicts with the current state of the server.
UnprocessableEntity	422	The request is well-formed but contains semantic errors.

Sources: packages/utils/spec/errors.md:12-17, packages/utils/test/errors.test.ts:16-43

Middleware and Global Handling

The API infrastructure uses a global errorHandler middleware to intercept thrown exceptions and convert them into standardized JSON responses.

Request Flow and Transformation

When an error occurs during request processing, the middleware evaluates if the error is an instance of AppError. If it is unknown (e.g., a native JavaScript Error), the system wraps it as a 500 INTERNAL_ERROR.

This flowchart illustrates how the middleware standardizes both known domain errors and unknown system errors.
Sources: apps/api/test/infrastructure/http/error-handler.test.ts:13-28, packages/utils/test/errors.test.ts:51-59

Error Conversion Rules

• AppError.from returns the same instance if the input is already an AppError.
• AppError.from returns a 500 INTERNAL_ERROR for unknown values.
• isServerError evaluates to true if the status code is 500 or greater.
• fieldErrors are carried through when provided, typically for INVALID_INPUT scenarios.

Sources: packages/utils/spec/errors.md:18-21, packages/utils/test/errors.test.ts:45-68

Protocol-Specific Handling

MCP Tool Errors

In the Model Context Protocol (MCP) layer, errors are caught and surfaced as tool-level errors. Even if a tool throws a domain error (like Conflict), the HTTP transport returns a 200 OK status, but the JSON-RPC result object contains an isError: true flag and the error message within the content.

• A private tool call on a public /mcp/:handle route returns a 404 status.
• A private tool call without a token on the bare /mcp route returns a 401 status.
• A tool execution failure (success or tool-level error) returns 200 with the error details in the body.

Sources: apps/api/test/infrastructure/http/server.integration.test.ts:210-250, apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:125-140

Application-Specific Error Codes

Modules define domain-specific codes that are carried by the errors. For example, the Bio module uses:

• BIO_NOT_FOUND: Returned when a specific handle does not exist.
• BIO_HANDLE_TAKEN: Returned when a user tries to claim a handle owned by another.

Sources: apps/api/spec/bio.md:38-65, apps/api/test/infrastructure/http/bio.router.test.ts:46-51

Summary

Standard Error Handling provides a predictable interface for error reporting by enforcing a hierarchy of AppError subclasses. The system automatically maps these classes to appropriate HTTP status codes and ensures that unknown failures are safely reported as internal server errors, while supporting specialized requirements for MCP tool communication and field-level validation.