From 076fac028cb8330c89386fe2a51ed59676e58773 Mon Sep 17 00:00:00 2001
From: GuticaStefan <stefan.gutica@gmail.com>
Date: Mon, 8 Dec 2025 14:01:57 +0200
Subject: [PATCH 1/2] add error handling docs

---
 .../rest-api/ws-subscriptions.md              | 49 ++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/docs/sdk-and-tools/rest-api/ws-subscriptions.md b/docs/sdk-and-tools/rest-api/ws-subscriptions.md
index 377c3eb4..79b648be 100644
--- a/docs/sdk-and-tools/rest-api/ws-subscriptions.md
+++ b/docs/sdk-and-tools/rest-api/ws-subscriptions.md
@@ -364,6 +364,52 @@ main().catch(console.error);
 
 ---
 
+## Error Handling
+
+Unexpected behaviors, such as sending an invalid payload or exceeding the server's subscription limits, will trigger an `error` event emitted by the server.
+
+You should listen to this event to handle failures gracefully.
+
+### Payload (DTO)
+
+The error object contains context about which subscription failed and why.
+
+| Field   | Type   | Description                                                                        |
+|---------|--------|------------------------------------------------------------------------------------|
+| pattern | string | The subscription topic (event name) that was requested (e.g., `subscribeTransactions`). |
+| data    | object | The original payload sent by the client that caused the error.                       |
+| error   | object | The specific error returned by the server.                                 |
+
+### Example usage
+
+```js
+import { io } from "socket.io-client";
+
+// ... setup socket connection ...
+
+// Listen for generic errors from the server
+socket.on("error", (errorData) => {
+  console.error("Received error from server:");
+  console.dir(errorData, { depth: null });
+});
+```
+
+### Error Example
+
+**Scenario:** The client attempts to open more subscriptions than the server allows (e.g., limit of X).
+
+```json
+{
+  "pattern": "subscribeCustomTransactions",
+  "data": { 
+    "function": "newGame" 
+  },
+  "error": "Maximum number of X global subscriptions accepted by server reached!"
+}
+```
+
+---
+
 ## Summary
 
 - WebSocket endpoint is dynamically obtained via `/websocket/config`.
@@ -371,6 +417,7 @@ main().catch(console.error);
 - Payload DTOs define allowed fields and required/optional rules.
 - Update messages mirror REST API and include `<resource>Count` fields.
 - `<resource>Count` reflects **total items at the moment of update**.
+- Errors are emitted via the standard `error` event, containing the pattern, original data, and error message.
 - Uses `socket.io-client`.
 
-This document contains everything required to use MultiversX WebSocket Subscriptions effectively.
+This document contains everything required to use MultiversX WebSocket Subscriptions effectively.
\ No newline at end of file

From 07e2ebf719491d03f3d295d4202cd08380ffb049 Mon Sep 17 00:00:00 2001
From: GuticaStefan <stefan.gutica@gmail.com>
Date: Mon, 8 Dec 2025 14:13:59 +0200
Subject: [PATCH 2/2] error example

---
 .../rest-api/ws-subscriptions.md              | 26 +++++++++++++++----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/docs/sdk-and-tools/rest-api/ws-subscriptions.md b/docs/sdk-and-tools/rest-api/ws-subscriptions.md
index 79b648be..3f7e1f4b 100644
--- a/docs/sdk-and-tools/rest-api/ws-subscriptions.md
+++ b/docs/sdk-and-tools/rest-api/ws-subscriptions.md
@@ -376,7 +376,7 @@ The error object contains context about which subscription failed and why.
 
 | Field   | Type   | Description                                                                        |
 |---------|--------|------------------------------------------------------------------------------------|
-| pattern | string | The subscription topic (event name) that was requested (e.g., `subscribeTransactions`). |
+| pattern | string | The subscription topic (event name) that was requested (e.g., `subscribePool`). |
 | data    | object | The original payload sent by the client that caused the error.                       |
 | error   | object | The specific error returned by the server.                                 |
 
@@ -400,11 +400,27 @@ socket.on("error", (errorData) => {
 
 ```json
 {
-  "pattern": "subscribeCustomTransactions",
-  "data": { 
-    "function": "newGame" 
+  "pattern": "subscribePool",
+  "data": {
+    "from": 0,
+    "size": 25,
+    "type": "badInput"
   },
-  "error": "Maximum number of X global subscriptions accepted by server reached!"
+  "error": [
+    {
+      "target": {
+        "from": 0,
+        "size": 25,
+        "type": "badInput"
+      },
+      "value": "badInput",
+      "property": "type",
+      "children": [],
+      "constraints": {
+        "isEnum": "type must be one of the following values: Transaction, SmartContractResult, Reward"
+      }
+    }
+  ]
 }
 ```