Merge pull request #1224 from GDLMadushanka/throwError

Add ThrowError mediator docs
wso2 · Jan 6, 2025 · 82be860 · 82be860
2 parents 42e0365 + 51e23d0
commit 82be860
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 0 deletions.
diff --git a/en/docs/reference/mediators/about-mediators.md b/en/docs/reference/mediators/about-mediators.md
@@ -276,6 +276,12 @@ WSO2 Micro Integrator includes a comprehensive catalog of mediators that provide
     </td>
     <td>Content-aware</td>
   </tr>
+  <tr>
+    <td>
+      <a href="{{base_path}}/reference/mediators/throw-error-mediator">ThrowError mediator</a>
+    </td>
+    <td>Conditionally content-aware</td>
+  </tr>
   <tr>
     <td>
       <a href="{{base_path}}/reference/mediators/callout-mediator">Callout mediator</a>

diff --git a/en/docs/reference/mediators/throw-error-mediator.md b/en/docs/reference/mediators/throw-error-mediator.md
@@ -0,0 +1,63 @@
+# ThrowError Mediator
+
+The ThrowError mediator allows you to throw an error from the mediation sequence. The error type and message can be customized as required.
+
+!!! Info 
+    Errors thrown by the ThrowError mediator is handled by the onError sequence (if defined) or the default fault sequence.
+
+## Syntax
+
+``` java
+<!-- Error message as string -->
+<throw-error type="string" errorMessage="string"></throw-error>
+<!-- Dynamic error message -->
+<throw-error type="string" errorMessage="{string}"></throw-error>
+```
+
+## Examples
+
+The following examples demonstrate the use of the ThrowError mediator.
+
+
+The following API configuration demonstrates how to use the ThrowError mediator to throw an error if a required field is not present in the incoming payload.
+
+``` xml
+<?xml version="1.0" encoding="UTF-8"?>
+<api context="/testThrowError" name="TestThrowErrorMediatorAPI" xmlns="http://ws.apache.org/ns/synapse">
+    <resource methods="POST">
+        <inSequence>
+            <filter xpath="${exists(payload.required)}">
+                <then>
+                    <log level="full"/>
+                    <respond/>
+                </then>
+                <else>
+                    <variable name="ERROR_MSG" value="Required field does not exist"/>
+                    <throwError type="PAYLOAD_ERROR" errorMessage="{${var.ERROR_MSG}}"/>
+                </else>
+            </filter>
+        </inSequence>
+        <faultSequence>
+            <log level="custom">
+                <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
+                <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
+            </log>
+            <drop/>
+        </faultSequence>
+    </resource>
+</api>
+```
+
+Invoking the above API with a payload that does not contain the required field will throw an error.
+```
+curl --location 'http://localhost:8290/testThrowError' \
+--header 'Content-Type: application/json' \
+--data '{
+    "Hello": "World"
+}'
+```
+
+The response log will contain the following error message:
+```
+INFO {LogMediator} - {api:TestThrowErrorMediatorAPI} ERROR_CODE = PAYLOAD_ERROR, ERROR_MESSAGE = Required field does not exist
+```
diff --git a/en/mkdocs.yml b/en/mkdocs.yml
@@ -851,6 +851,7 @@ nav:
               - Store Mediator: reference/mediators/store-mediator.md
               - Switch Mediator: reference/mediators/switch-mediator.md
               - Throttle Mediator: reference/mediators/throttle-mediator.md
+              - ThrowError Mediator: reference/mediators/throw-error-mediator.md
               - Transaction Mediator: reference/mediators/transaction-mediator.md
               - URLRewrite Mediator: reference/mediators/urlrewrite-mediator.md
               - Validate Mediator: reference/mediators/validate-mediator.md