Errors and exceptions

This page lists the error classes and codes of Cluster ERP and how the server turns exceptions into HTTP responses. It covers core/errors.py, core/exceptions.py, and server/error_handler.py. The full list of codes with their causes, as a client sees them, is on API errors.

Scope and source¶

• Defined in: src/cluster_erp/core/errors.py (AppError, code constants, factories), src/cluster_erp/core/exceptions.py (platform exceptions), src/cluster_erp/server/error_handler.py (install_error_handlers)
• Count: 213 module-level string constants of the form NAME = "NAME" in core/errors.py (counted with grep -c -E '^[A-Z_0-9]+ = "'), in 23 commented groups; 6 factory functions; 7 exception classes in core/exceptions.py (counted with grep -c "^class")

The error body¶

Every handled error returns a JSON body built by _build_body (src/cluster_erp/server/error_handler.py:33-46):

{
 "error": {
 "code": "<CODE>",
 "message": "<developer message>",
 "trace_id": "<YYMMDD-NNN>",
 "details": {}
 }
}

details is present only when it is not empty. In debug mode the unhandled-exception handler adds debug_message and exception_type, and the mapped handlers add debug_message (src/cluster_erp/server/error_handler.py:305-308, src/cluster_erp/server/error_handler.py:345-347). debug_message carries at most the first line of the driver message, cut to 300 characters, never the SQL text (src/cluster_erp/server/error_handler.py:99-107).

Trace ids¶

_next_trace_id increments a per-day counter in the table trace_sequence and returns YYMMDD-NNN. If the database is unreachable it returns YYMMDD- with eight digits taken from a monotonic clock (src/cluster_erp/server/error_handler.py:49-70). The table comes from the migration feefe25508db_add_trace_sequence_table.py. Handlers store the trace id and error data on request.state; the activity-log middleware writes them to the error log (src/cluster_erp/server/error_handler.py:73-93, src/cluster_erp/server/middleware.py:638-659).

AppError¶

AppError(code, message, *, status_code=400, details=None) is the exception that services and routes raise (src/cluster_erp/core/errors.py:6-30). The code is machine-readable, the client maps it to a localised text, and the message is an English developer string (src/cluster_erp/core/errors.py:7-16).

Code groups¶

Some modules define further codes in their own files, for example CURRENCY_UNKNOWN (src/cluster_erp/core/currencies.py:27) and UPLOAD_TYPE_REFUSED (src/cluster_erp/core/upload_policy.py:19). They are not counted above.

Factories¶

Exception handlers¶

install_error_handlers(app, debug) registers the handlers below (src/cluster_erp/server/error_handler.py:200-398).

A 503 response from the unhandled-exception handler carries Retry-After: 2 (src/cluster_erp/server/error_handler.py:309). Each mapped type gets its own handler so that Starlette's exception middleware handles it instead of the server-error middleware (src/cluster_erp/server/error_handler.py:312-318, src/cluster_erp/server/error_handler.py:394-398).

Platform exceptions¶

These classes in core/exceptions.py are raised by the module registry and the EventBus. They are not mapped to HTTP codes.

Constraints and validation¶

• A request body larger than max_request_body_bytes is refused with HTTP 413 and code REQUEST_TOO_LARGE by a middleware, before any handler runs (src/cluster_erp/server/app.py:1396-1410). That code is not one of the constants in core/errors.py.
• A RESOURCE_PROTECTED error uses HTTP 400, not 403 (src/cluster_erp/core/errors.py:379-385).

Terms introduced¶

Related pages¶

• Platform core
• API errors
• Request pipeline and middleware
• Logs

Verified against commit 92f8051 on 2026-11-13.