From 2c92aa4290c7636d8ca9c2bce038c0f33ba2e348 Mon Sep 17 00:00:00 2001
From: Quentin Focheux <quentin@privateaser.com>
Date: Fri, 17 Oct 2025 18:00:03 +0200
Subject: [PATCH] feat: add specific error class when Sms.send_message is
 throttled

---
 sms/src/vonage_sms/errors.py                  |  4 ++++
 sms/src/vonage_sms/sms.py                     |  8 +++++++-
 sms/tests/data/send_sms_error_throttling.json |  9 +++++++++
 sms/tests/test_sms.py                         | 13 ++++++++++++-
 4 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 sms/tests/data/send_sms_error_throttling.json

diff --git a/sms/src/vonage_sms/errors.py b/sms/src/vonage_sms/errors.py
index fa399c14..59ae9130 100644
--- a/sms/src/vonage_sms/errors.py
+++ b/sms/src/vonage_sms/errors.py
@@ -15,3 +15,7 @@ def __init__(self, response: Response):
         )
         super().__init__(self.message)
         self.response = response
+
+
+class SmsThrottleError(SmsError):
+    """Indicates that the SMS requests are being throttled due to too many requests in a short period."""
diff --git a/sms/src/vonage_sms/sms.py b/sms/src/vonage_sms/sms.py
index b9e4b6ba..782f97d7 100644
--- a/sms/src/vonage_sms/sms.py
+++ b/sms/src/vonage_sms/sms.py
@@ -3,7 +3,7 @@
 from pydantic import validate_call
 from vonage_http_client.http_client import HttpClient
 
-from .errors import PartialFailureError, SmsError
+from .errors import PartialFailureError, SmsError, SmsThrottleError
 from .requests import SmsMessage
 from .responses import SmsResponse
 
@@ -86,6 +86,12 @@ def _check_for_partial_failure(self, response_data):
     def _check_for_error(self, response_data):
         message = response_data['messages'][0]
         if int(message['status']) != 0:
+            # List of SMS API error codes is available at:
+            # https://developer.vonage.com/en/messaging/sms/guides/troubleshooting-sms#sms-api-error-codes
+            if int(message['status']) == 1:
+                raise SmsThrottleError(
+                    f'Sms.send_message method failed due to throttling: {message["error-text"]}'
+                )
             raise SmsError(
                 f'Sms.send_message method failed with error code {message["status"]}: {message["error-text"]}'
             )
diff --git a/sms/tests/data/send_sms_error_throttling.json b/sms/tests/data/send_sms_error_throttling.json
new file mode 100644
index 00000000..5873c4a7
--- /dev/null
+++ b/sms/tests/data/send_sms_error_throttling.json
@@ -0,0 +1,9 @@
+{
+    "message-count": "1",
+    "messages": [
+        {
+            "status": "1",
+            "error-text": "You are sending SMS faster than the account limit."
+        }
+    ]
+}
\ No newline at end of file
diff --git a/sms/tests/test_sms.py b/sms/tests/test_sms.py
index 46d5da78..f5177c4d 100644
--- a/sms/tests/test_sms.py
+++ b/sms/tests/test_sms.py
@@ -7,7 +7,7 @@
 from vonage_http_client.errors import HttpRequestError
 from vonage_http_client.http_client import HttpClient
 from vonage_sms import Sms
-from vonage_sms.errors import PartialFailureError, SmsError
+from vonage_sms.errors import PartialFailureError, SmsError, SmsThrottleError
 from vonage_sms.requests import SmsMessage
 
 from testutils import build_response
@@ -145,6 +145,17 @@ def test_send_message_error():
             str(err) == 'Sms.send_message method failed with error code 7: Number barred.'
         )
 
+@responses.activate
+def test_send_message_error_throttling():
+    build_response(path, 'POST', 'https://rest.nexmo.com/sms/json', 'send_sms_error_throttling.json')
+    message = SmsMessage(to='1234567890', from_='Acme Inc.', text='Hello, World!')
+    try:
+        sms.send(message)
+    except SmsThrottleError as err:
+        assert (
+            str(err) == 'Sms.send_message method failed due to throttling: You are sending SMS faster than the account limit.'
+        )
+
 
 @responses.activate
 def test_submit_sms_conversion():