From d3b6b8d2047939d598f99646de76d410cc26ce58 Mon Sep 17 00:00:00 2001
From: GDLMadushanka <gdlmadushanka@gmail.com>
Date: Fri, 3 Jan 2025 12:23:15 +0530
Subject: [PATCH] Add ThrowError mediator docs

Add ThrowError mediator docs
Related to wso2/product-micro-integrator/issues/3843
---
 .../reference/mediators/about-mediators.md    |  6 ++
 .../mediators/throw-error-mediator.md         | 64 +++++++++++++++++++
 en/mkdocs.yml                                 |  1 +
 3 files changed, 71 insertions(+)
 create mode 100644 en/docs/reference/mediators/throw-error-mediator.md

diff --git a/en/docs/reference/mediators/about-mediators.md b/en/docs/reference/mediators/about-mediators.md
index 20eefeb89..4604e0bf0 100644
--- 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
new file mode 100644
index 000000000..6347ae616
--- /dev/null
+++ b/en/docs/reference/mediators/throw-error-mediator.md
@@ -0,0 +1,64 @@
+# ThrowError Mediator
+
+The ThrowError mediator allows you to raise 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
+
+Following examples demonstrate the use of Throw Error mediator.
+
+### Example 1
+
+The following API configuration demonstrates how to use the Throw Error mediator to raise an error when some 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 raise an error.
+```
+curl --location 'http://localhost:8290/testThrowError' \
+--header 'Content-Type: application/json' \
+--data '{
+    "Hello": "World"
+}'
+```
+
+Response log will contain the error message as follows.
+```
+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
index 6012b90c2..eb577fb85 100644
--- a/en/mkdocs.yml
+++ b/en/mkdocs.yml
@@ -860,6 +860,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