You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+35-15Lines changed: 35 additions & 15 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# API Error Handler
2
2
3
-
This error handler module processes any errors thrown in a flow and transforms to the correct JSON response body and HTTP status code for an API.
3
+
The error handler module processes any errors thrown in a flow and transforms to the correct JSON response body and HTTP status code for an API.
4
+
5
+
*This requires the [MuleSoft Enterprise Maven Repository][mule-ee] to compile and use.*
4
6
5
7
All APIKit and HTTP exceptions are handled by the module and can be customized in the *Common Errors* tab. Additional error definitions can be added via dataweave in the *Custom Errors* tab.
6
8
@@ -106,6 +108,7 @@ The groupId value must be the appropriate Anypoint Org Id where the module is de
@@ -234,7 +236,7 @@ The custom errors must be an *object of objects* with the fields below.
234
236
-`reason`: Error reason phrase to send in JSON body response. This is a string.
235
237
-`message`: Error details to send in JSON body response. A string is preferred for this field, but any type is allowed.
236
238
237
-
dataweave script is allowed in each field value. To access the error object in this definition, you use `error` as normal.
239
+
Dataweave script is allowed in each field value. To access the error object in this definition, you use `error` as normal.
238
240
239
241
**Custom errors override common errors.** If you want to override a common error's status or reason, and not just the message, you would add an entry for that error in the custom errors definition, which will completely override the common error.
240
242
@@ -245,13 +247,35 @@ A template custom error file, [examples/customErrors.dwl](./examples/customError
245
247
- Unknown error handler: `MULE:UNKNOWN`. This is recommended when you want to propagate message and error code from non-standard errors, like `495`.
246
248
247
249
```
250
+
/**
251
+
* This provides custom error handling for the API Error Handler.
252
+
*/
253
+
248
254
%dw 2.0
249
255
output application/json
250
-
251
256
import * from module_error_handler_plugin::common
252
257
253
-
// Previous error nested in the Mule error object, which conforms to the API Error Handler responses.
254
-
var previousError = getPreviousErrorMessage(error)
258
+
/**
259
+
* Previous error nested in the Mule error object.
260
+
* Provides the entire payload of the previous error as a String.
261
+
* Handles the main Mule Error formats to get nested errors:
262
+
* - Composite modules/scopes, like Scatter-Gather, Parallel-Foreach, Group Validation Module
263
+
* - Until-Successful
264
+
* - Standard Error, like Raise Error, Foreach, and most connectors and errors.
error.exception.errorMessage.typedValue // Standard Error: must go last because it has content if this is one of the other types of errors
271
+
] dw::core::Arrays::firstWith !isEmpty($)
272
+
---
273
+
if (nested is Array)
274
+
toString(nested map (toString($)) distinctBy $)
275
+
else
276
+
toString(nested)
277
+
}
278
+
255
279
---
256
280
{
257
281
/*
@@ -305,7 +329,6 @@ var previousError = getPreviousErrorMessage(error)
305
329
### Common Functions
306
330
There are some common functions provided by the module that you can use in your custom errors definition. They are imported by `import * from module_error_handler_plugin::common`.
307
331
308
-
-`getPreviousErrorMessage`: Gets the downstream API's error message text when an error is returned from that API. This should only used when the called API uses this same error module. Any other response structure must be manually handled by dataweave. It takes the error object as a parameter. This is a great way to propagate errors up the API stack without losing the original error.
309
332
-`getErrorTypeAsString`: Gets the string for the current Mule error type. This corresponds to the *keys* in the custom error object. Example: `HTTP:INTERNAL_SERVER_ERROR`.
310
333
-`toString`: Converts any type to a string. If not a string, it uses write() with Java format. If empty, then returns empty string or the value specified in the second parameter.
311
334
@@ -322,17 +345,13 @@ The error object definition takes the standard [Mule Error][mule-error] by defau
322
345
### Use Previous Error
323
346
Connectors usually generate error responses their own error responses and wrap the actual error response from the external system in the error object. This causes the external system's response to be lost and not propagated back to the API's caller. The previous error feature allows the module to retrieve the external system's error response from the error object and use that as the error message.
324
347
325
-
A common scenario is when a system API generates an error that needs to get propagated back to the caller of the experience or process API. Using normal error handling, like `error.description`, the SOAP fault or `500` response from the called system is not logged or propagated. These items are nested in the error object here: `error.exception.errorMessage.payload` and `error.exception.errorMessage.attributes`.
348
+
A common scenario is when a system API generates an error that needs to get propagated back to the caller of the experience or process API. Using normal error handling, like `error.description`, the SOAP fault or `500` response from the called system is not logged or propagated. These items are nested in the error object here: `error.exception.errorMessage.typedValue.payload` and `error.exception.errorMessage.typedValue.attributes`. Be aware that payload and attributes won't be accessable by selector if the content is `Binary`. If the type is `Binary`, then you must read the error payload, `error.exception.errorMessage.typedValue`, as the correct MIME type if you want to access a specific field using a selector.
326
349
327
350
This feature will automatically replace the `message` field for ***all errors*** with the previous error defined by the provided dataweave if one exists. If the previous error does not exist or is empty, then it will leave the `message` field with its current value. This feature does not append the previous error to the current one. It simply replaces and is best used to propagate downstream errors up the API stack.
328
351
329
-
The dataweave should resolve to a string but any type is allowed. The default value below resolves to a called Mule API's error message, if the message is in `error.message` in the response body, which conforms to the API Error Handler responses.
The dataweave should resolve to a string but any type is allowed. You can override in any manner; the template custom error file gives a comprehensive example on how to convert nested errors to strings.
334
353
335
-
**Set this field to an empty string if you do not want to propagate previous errors.**
354
+
**Set this field to an empty string if you do not want to propagate previous errors. This is the default value**
336
355
337
356
### Response Key Name for Payload
338
357
This field allows you to customize the JSON key name where the error payload is set. This defaults to `error`, which is shown in the examples. This only supports changing the name of the top-level key; it does not change any other format. If you want the error payload to be the top-level element in the response, then set this field to empty string.
@@ -465,6 +484,7 @@ It takes the parameters below.
0 commit comments