Errors

This page describes the error body that every failed API request returns and lists every error code found in code. It covers the 213 code constants in src/cluster_erp/core/errors.py, the codes that modules and server files define locally, and the codes that the exception handlers in src/cluster_erp/server/error_handler.py assign. The design of the error model is explained in Errors and exceptions.

Error body¶

Every handler builds the body with _build_body. From src/cluster_erp/server/error_handler.py:33-46:

def _build_body(
    code: str,
    message: str,
    trace_id: str,
    details: dict[str, Any] | None = None,
) -> dict[str, Any]:
    body: dict[str, Any] = {
        "code": code,
        "message": message,
        "trace_id": trace_id,
    }
    if details:
        body["details"] = details
    return {"error": body}

Illustrative response built from _build_body and the RESOURCE_NOT_FOUND factory not_found (src/cluster_erp/core/errors.py:357-367):

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Warehouse (<warehouse_id>) not found",
    "trace_id": "<yymmdd>-<seq>",
    "details": {"resource": "Warehouse", "id": "<warehouse_id>"}
  }
}

Exception handlers¶

install_error_handlers registers one handler per exception class (src/cluster_erp/server/error_handler.py:200-398). The table lists what each produces.

Codes common to every route¶

Authentication, permission, and entitlement checks run before a handler and can answer any route. The entitlement gate raises HTTPException with a dict detail, so the code reaches the body as code (src/cluster_erp/server/entitlements.py:233-257, src/cluster_erp/server/error_handler.py:252-262).

Codes defined in the core error module¶

One table per comment section of src/cluster_erp/core/errors.py. Status, raise-site count, and first site come from a syntax-tree scan of src/cluster_erp/ for AppError(...), the factories in core/errors.py, and HTTPException(...). The message column quotes the English message at the first site; it is the cause as the code states it. A code with no raise site is defined but not raised by any scanned call. Codes the exception handlers assign show the handler instead.

Codes of the business sections of the same file (CRM to procurement) are listed on Business error codes.

Auth¶

Resource CRUD¶

Validation¶

Business logic¶

Currency¶

Concurrency¶

External services¶

Database¶

Serialization¶

Runtime¶

Server¶

Codes defined outside the core error module¶

These codes are string constants or literals in a module or server file. Rows are grouped by the folder of the first raise site.

Generic HTTP codes¶

An HTTPException with a plain detail becomes HTTP_<status> (src/cluster_erp/server/error_handler.py:251).

Related pages¶

• API reference
• Business error codes
• Errors and exceptions
• Authentication and headers
• API conventions

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