feat: add specific error class when Sms.send_message is throttled

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."""

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"]}'
             )

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."
+        }
+    ]
+}

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():