10.1 Mule 4 Error Object Hierarchy & Custom Error Types

Mule 4 Error Object Hierarchy & Custom Error Types

In Mule 4, error handling is fundamentally re-architected around an explicit, declarative, and type-safe error handling framework. Unlike earlier Mule versions or traditional Java-based frameworks that rely on low-level Java exception classes, Mule 4 abstracts failures into a structured Error Object and a declarative Error Type Hierarchy. Understanding the composition of the Error Object, how error namespaces operate, and how to define and raise custom business errors is a foundational requirement for the Salesforce Certified MuleSoft Developer I examination.

---

1. Mule 4 Error Object Architecture

Whenever a message processor, connector operation, or routing component throws an exception during message processing, the Mule runtime intercepts the failure, halts normal sequential flow execution, and instantiates an immutable Error Object bound to the keyword error.

+---------------------------------------------------------------------------------------------------+
|                                    MULE 4 ERROR OBJECT STRUCTURE                                  |
|                                                                                                   |
|   error                                                                                           |
|   |                                                                                               |
|   +--- description              : String  ("HTTP GET on 'https://api.acme.com/v1/users' failed") |
|   +--- detailedDescription      : String  ("HTTP GET on resource failed with status code 404")    |
|   +--- exception                : Object  (Underlying Java Exception / Stack Trace)               |
|   +--- childErrors              : Object  (Map of child Error Objects, e.g. in Scatter-Gather)    |
|   |                                                                                               |
|   +--- errorType                : Object  (Complex Error Type Definition)                         |
|   |    +--- namespace           : String  ("HTTP")                                                |
|   |    +--- identifier          : String  ("NOT_FOUND")                                           |
|   |    +--- parentErrorType     : Object  (Reference to parent type: HTTP:ANY -> ANY)             |
|   |                                                                                               |
|   +--- errorMessage             : MuleMessage (Response message emitted by the failing target)     |
|        +--- payload             : Object  ({ "code": "USER_NOT_FOUND", "message": "User #88..." })|
|        +--- attributes          : Object  ({ statusCode: 404, headers: { ... } })                 |
+---------------------------------------------------------------------------------------------------+

Key Properties of the error Object

[!IMPORTANT] Preserving Backend API Error Payloads via error.errorMessage A very common certification exam scenario asks how to retrieve the exact JSON or XML error response sent by an external REST API when an <http:request> call fails with status 400, 404, or 500. In Mule 4, the external response payload is stored in error.errorMessage.payload, NOT in error.description or the top-level payload. Accessing payload inside an error handler will reflect whatever payload was in the flow prior to the failing processor, unless explicitly overwritten.

---

2. Mule 4 Error Type Hierarchy

Mule 4 structures all error types into a single, unified taxonomy tree. At the highest level, errors are divided into two fundamental branches: ANY and CRITICAL.

                                   [ ERROR ROOT ]
                                         |
                    +--------------------+--------------------+
                    |                                         |
                 [ ANY ]                                 [ CRITICAL ]
             (Catchable Errors)                     (Non-Catchable Errors)
                    |                                         |
     +--------------+--------------+                          +-- FATAL_JVM_ERROR
     |              |              |                          +-- OUT_OF_MEMORY
[ CORE TYPES ] [ CONNECTORS ] [ CUSTOM TYPES ]                +-- OVERLOAD
     |              |              |
     +-- EXPRESSION +-- HTTP       +-- ORDER:INVALID_ITEM
     |              |   +-- CONNECTIVITY
     +-- ROUTING    |   +-- NOT_FOUND
     |   +-- COMPOSITE_ROUTING
     |              +-- DB
     +-- SECURITY       +-- CONNECTIVITY
     |   +-- CLIENT_SECURITY
     |                  +-- VALIDATION
     +-- TRANSFORMATION     +-- INVALID_BOOLEAN

The ANY Hierarchy (Catchable Errors)

ANY is the root type of all catchable errors. Any error handler configured with type="ANY" will intercept any error falling under this branch, regardless of the connector, module, or custom namespace.

The CRITICAL Hierarchy (Non-Catchable Errors)

CRITICAL errors represent fatal, unrecoverable system or JVM-level failures where runtime stability is compromised. CRITICAL errors cannot be handled or caught by <on-error-continue> or <on-error-propagate> scopes. When a CRITICAL error occurs, Mule logs the failure and immediately halts execution.

Standard CRITICAL error types include:

• FATAL_JVM_ERROR: An unrecoverable JVM crash or internal error.
• OUT_OF_MEMORY: The JVM has exhausted its heap space.
• OVERLOAD: The system is overloaded and unable to allocate threads or memory buffers.

---

3. Core Built-In Error Namespaces and Identifiers

Mule 4 standardizes error types using the format NAMESPACE:IDENTIFIER. All namespaces and identifiers are uppercase.

Built-in Core and Connector Error Taxonomy

Generalization and Matching Rules

Because error types exist in a hierarchical taxonomy:

• An error handler matching ANY will match all errors above except CRITICAL.
• An error handler matching CONNECTIVITY will catch both HTTP:CONNECTIVITY and DB:CONNECTIVITY.
• An error handler matching HTTP:ANY will catch HTTP:NOT_FOUND, HTTP:UNAUTHORIZED, HTTP:CONNECTIVITY, and all other HTTP:* errors.
• An error handler matching HTTP:CLIENT_SECURITY will catch HTTP:UNAUTHORIZED and HTTP:FORBIDDEN.

---

4. Custom Error Types & The <raise-error> Processor

In real-world enterprise applications, business rule failures (e.g., insufficient account balance, customer not found, invalid inventory quantity) should be handled using the same declarative error mechanism as technical exceptions. Mule 4 enables developers to throw custom errors using the <raise-error> processor.

Declaring Custom Errors

<flow name="process-withdrawal-flow" doc:name="Process Withdrawal Flow">
    <http:listener config-ref="HTTP_Listener_config" path="/accounts/{id}/withdraw" doc:name="Listener"/>
    
    <!-- Validate Account Balance -->
    <choice doc:name="Check Balance">
        <when expression="#[vars.accountBalance &lt; payload.amount]">
            <!-- Raise Custom Business Error -->
            <raise-error 
                type="ACCOUNT:INSUFFICIENT_FUNDS" 
                description="The account balance is insufficient for the requested withdrawal amount." 
                doc:name="Raise Insufficient Funds"/>
        </when>
        <otherwise>
            <logger level="INFO" message="Funds verified. Processing transaction..." doc:name="Log OK"/>
        </otherwise>
    </choice>
    
    <!-- Error Handler in Flow -->
    <error-handler>
        <!-- Catch specific custom error -->
        <on-error-continue type="ACCOUNT:INSUFFICIENT_FUNDS" doc:name="Catch Insufficient Funds">
            <set-payload value="#[{ 'error': 'DECLINED', 'message': error.description, 'type': error.errorType.identifier }]" doc:name="Set Payload"/>
            <set-variable variableName="httpStatus" value="422" doc:name="Set 422 Status"/>
        </on-error-continue>
        
        <!-- Catch all other custom ACCOUNT errors -->
        <on-error-propagate type="ACCOUNT:ANY" doc:name="Catch Other Account Errors">
            <logger level="ERROR" message="#['General Account error: ' ++ error.description]" doc:name="Log Error"/>
        </on-error-propagate>
    </error-handler>
</flow>

Rules for Custom Error Types:

1. Format: Must follow the CUSTOM_NAMESPACE:IDENTIFIER pattern (e.g., ORDER:ITEM_OUT_OF_STOCK, AUTH:EXPIRED_TOKEN).
2. Case Sensitivity: Both namespace and identifier must consist of uppercase letters, numbers, and underscores.
3. Reserved Namespaces: You must not use reserved system namespaces (MULE, HTTP, DB, FILE, WSC, VALIDATION, APIKIT, etc.) for custom errors.
4. Hierarchy Inheritance: Custom error types automatically become children of the root ANY type. They also automatically support the NAMESPACE:ANY wildcard (e.g., matching ACCOUNT:ANY catches ACCOUNT:INSUFFICIENT_FUNDS, ACCOUNT:NOT_FOUND, etc.).

---

5. Inspecting Error Details in DataWeave

Inside error handler message processors (such as <ee:transform>, <set-payload>, or <logger>), developers can inspect the error object using DataWeave to construct standardized API error responses conforming to RFC 7807:

%dw 2.0
output application/json
---
{
    timestamp: now(),
    status: vars.httpStatus default 500,
    errorType: {
        namespace: error.errorType.namespace default "UNKNOWN",
        identifier: error.errorType.identifier default "UNKNOWN",
        canonicalName: (error.errorType.namespace default "UNKNOWN") ++ ":" ++ (error.errorType.identifier default "UNKNOWN")
    },
    message: error.description,
    detailedMessage: error.detailedDescription,
    backendResponse: error.errorMessage.payload default null,
    failedRouteErrors: error.childErrors default null
}

---

6. Exam Watch: Core Error Hierarchy Scenarios

[!IMPORTANT] Accessing error.errorMessage.payload vs payload When an HTTP Request operation fails with a 4xx/5xx status code, the response body from the remote server is placed in error.errorMessage.payload. The top-level payload variable in the flow remains the payload that existed before the failing component executed.

[!WARNING] CRITICAL Errors Cannot Be Caught If an exam question asks what error handler scope intercepts a MULE:FATAL_JVM_ERROR or MULE:OUT_OF_MEMORY, the answer is none. CRITICAL errors bypass all <error-handler>, <on-error-continue>, and <on-error-propagate> scopes.

[!TIP] Matching Order Hierarchy When an error occurs, Mule matches against the most specific type first. If an error handler has a scope matching HTTP:CONNECTIVITY and a scope matching CONNECTIVITY, an HTTP:CONNECTIVITY error will match HTTP:CONNECTIVITY. However, if the scopes are defined sequentially in the XML, Mule evaluates them in declaration order!