Add BaseFailed exceptions for phone_notificator

engine/apps/api/views/user.py

@@ -43,6 +43,7 @@
 from apps.mobile_app.demo_push import send_test_push
 from apps.mobile_app.exceptions import DeviceNotSet
 from apps.phone_notifications.exceptions import (
+    BaseFailed,
     FailedToFinishVerification,
     FailedToMakeCall,
     FailedToStartVerification,
@@ -340,8 +341,8 @@ def get_verification_code(self, request, pk):
             phone_backend.send_verification_sms(user)
         except NumberAlreadyVerified:
             return Response("Phone number already verified", status=status.HTTP_400_BAD_REQUEST)
-        except FailedToStartVerification:
-            return Response("Something went wrong while sending code", status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+        except FailedToStartVerification as e:
+            return handle_phone_notificator_failed(e)
         except ProviderNotSupports:
             return Response(
                 "Phone provider not supports sms verification", status=status.HTTP_500_INTERNAL_SERVER_ERROR
@@ -367,8 +368,8 @@ def get_verification_call(self, request, pk):
             phone_backend.make_verification_call(user)
         except NumberAlreadyVerified:
             return Response("Phone number already verified", status=status.HTTP_400_BAD_REQUEST)
-        except FailedToStartVerification:
-            return Response("Something went wrong while calling", status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+        except FailedToStartVerification as e:
+            return handle_phone_notificator_failed(e)
         except ProviderNotSupports:
             return Response(
                 "Phone provider not supports call verification", status=status.HTTP_500_INTERNAL_SERVER_ERROR
@@ -390,8 +391,8 @@ def verify_number(self, request, pk):
         phone_backend = PhoneBackend()
         try:
             verified = phone_backend.verify_phone_number(target_user, code)
-        except FailedToFinishVerification:
-            return Response("Something went wrong while verifying code", status=status.HTTP_503_SERVICE_UNAVAILABLE)
+        except FailedToFinishVerification as e:
+            return handle_phone_notificator_failed(e)
         if verified:
             new_state = target_user.insight_logs_serialized
             write_resource_insight_log(
@@ -432,10 +433,8 @@ def make_test_call(self, request, pk):
             phone_backend.make_test_call(user)
         except NumberNotVerified:
             return Response("Phone number is not verified", status=status.HTTP_400_BAD_REQUEST)
-        except FailedToMakeCall:
-            return Response(
-                "Something went wrong while making a test call", status=status.HTTP_500_INTERNAL_SERVER_ERROR
-            )
+        except FailedToMakeCall as e:
+            return handle_phone_notificator_failed(e)
         except ProviderNotSupports:
             return Response("Phone provider not supports phone calls", status=status.HTTP_500_INTERNAL_SERVER_ERROR)
 
@@ -449,10 +448,8 @@ def send_test_sms(self, request, pk):
             phone_backend.send_test_sms(user)
         except NumberNotVerified:
             return Response("Phone number is not verified", status=status.HTTP_400_BAD_REQUEST)
-        except FailedToMakeCall:
-            return Response(
-                "Something went wrong while making a test call", status=status.HTTP_500_INTERNAL_SERVER_ERROR
-            )
+        except FailedToMakeCall as e:
+            return handle_phone_notificator_failed(e)
         except ProviderNotSupports:
             return Response("Phone provider not supports phone calls", status=status.HTTP_500_INTERNAL_SERVER_ERROR)
 
@@ -650,3 +647,10 @@ def check_availability(self, request, pk):
         user = self.get_object()
         warnings = check_user_availability(user=user, team=request.user.current_team)
         return Response(data={"warnings": warnings}, status=status.HTTP_200_OK)
+
+
+def handle_phone_notificator_failed(exc: BaseFailed) -> Response:
+    if exc.graceful_msg:
+        return Response(exc.graceful_msg, status=status.HTTP_400_BAD_REQUEST)
+    else:
+        return Response("Something went wrong", status=status.HTTP_503_SERVICE_UNAVAILABLE)

engine/apps/phone_notifications/exceptions.py

@@ -1,24 +1,40 @@
-class FailedToMakeCall(Exception):
+class BaseFailed(Exception):
+    """
+    Failed is base exception for all Failed... exceptions.
+    This exception is indicates error while performing some phone notification operation.
+    Optionally can contain graceful_msg attribute. When graceful_msg is provided it mean that error on provider side is
+    not our fault, but some provider error (number is blocked, fraud guard, ...).
+    By default, graceful_msg is None - it means that error is our fault (network problems, invalid configuration,...).
+
+    Attributes:
+       graceful_msg: string with some details about exception which can be exposed to caller.
+    """
+
+    def __init__(self, graceful_msg=None):
+        self.graceful_msg = graceful_msg
+
+
+class FailedToMakeCall(BaseFailed):
     pass
 
 
-class FailedToSendSMS(Exception):
+class FailedToSendSMS(BaseFailed):
     pass
 
 
-class NumberNotVerified(Exception):
+class FailedToStartVerification(BaseFailed):
     pass
 
 
-class NumberAlreadyVerified(Exception):
+class FailedToFinishVerification(BaseFailed):
     pass
 
 
-class FailedToStartVerification(Exception):
+class NumberNotVerified(Exception):
     pass
 
 
-class FailedToFinishVerification(Exception):
+class NumberAlreadyVerified(Exception):
     pass
 
 

engine/apps/twilioapp/phone_provider.py

@@ -43,14 +43,14 @@ def make_notification_call(self, number: str, message: str) -> TwilioPhoneCall:
                 try_without_callback = True
             else:
                 logger.error(f"TwilioPhoneProvider.make_notification_call: failed {e}")
-                raise FailedToMakeCall
+                raise FailedToMakeCall(graceful_msg=self._get_graceful_msg(e, number))
 
         if try_without_callback:
             try:
                 response = self._call_create(twiml_query, number, with_callback=False)
             except TwilioRestException as e:
                 logger.error(f"TwilioPhoneProvider.make_notification_call: failed {e}")
-                raise FailedToMakeCall
+                raise FailedToMakeCall(graceful_msg=self._get_graceful_msg(e, number))
 
         if response and response.status and response.sid:
             return TwilioPhoneCall(
@@ -72,14 +72,14 @@ def send_notification_sms(self, number: str, message: str) -> TwilioSMS:
                 try_without_callback = True
             else:
                 logger.error(f"TwilioPhoneProvider.send_notification_sms: failed {e}")
-                raise FailedToSendSMS
+                raise FailedToSendSMS(graceful_msg=self._get_graceful_msg(e, number))
 
         if try_without_callback:
             try:
                 response = self._messages_create(number, message, with_callback=False)
             except TwilioRestException as e:
                 logger.error(f"TwilioPhoneProvider.send_notification_sms: failed {e}")
-                raise FailedToSendSMS
+                raise FailedToSendSMS(graceful_msg=self._get_graceful_msg(e, number))
 
         if response and response.status and response.sid:
             return TwilioSMS(
@@ -106,24 +106,51 @@ def finish_verification(self, number: str, code: str):
                     return normalized_number
             except TwilioRestException as e:
                 logger.error(f"TwilioPhoneProvider.finish_verification: failed to verify number {number}: {e}")
-                raise FailedToFinishVerification
+                raise FailedToFinishVerification(graceful_msg=self._get_graceful_msg(e, number))
         else:
             return None
 
+    """
+    Errors we will raise without graceful messages:
+
+    20404 - We should not be requesting missing resources
+    30808 - Unknown error, likely on the carrier side
+    30007, 32017 - Blocked or filtered, Intermediary / Carrier Analytics blocked call
+                due to poor reputation score on the telephone number:
+        * We need to register our number or sender with the analytics provider or carrier for that jurisdiction
+    """
+
+    def _get_graceful_msg(self, e, number):
+        if e.code in (30003, 30005):
+            raise f"Destination handset {number} is unreachable"
+        elif e.code == 30004:
+            return f"Sending message to {number} is blocked"
+        elif e.code == 30006:
+            return f"Cannot send to {number} is landline or unreachable carrier"
+        elif e.code == 30410:
+            return f"Provider for {number} is experiencing timeouts"
+        elif e.code == 60200:
+            return f"{number} is incorrectly formatted"
+        elif e.code in (60410, 60605):
+            return f"Verification to {number} is blocked"
+        elif e.code == 60203:
+            return f"Max verification attempts for {number} reached"
+        return None
+
     def make_call(self, number: str, message: str):
         twiml_query = self._message_to_twiml(message, with_gather=False)
         try:
             self._call_create(twiml_query, number, with_callback=False)
         except TwilioRestException as e:
             logger.error(f"TwilioPhoneProvider.make_call: failed {e}")
-            raise FailedToMakeCall
+            raise FailedToMakeCall(graceful_msg=self._get_graceful_msg(e, number))
 
     def send_sms(self, number: str, message: str):
         try:
             self._messages_create(number, message, with_callback=False)
         except TwilioRestException as e:
             logger.error(f"TwilioPhoneProvider.send_sms: failed {e}")
-            raise FailedToSendSMS
+            raise FailedToSendSMS(graceful_msg=self._get_graceful_msg(e, number))
 
     def _message_to_twiml(self, message: str, with_gather=False):
         q = f"<Response><Say>{message}</Say></Response>"
@@ -178,7 +205,7 @@ def _send_verification_code(self, number: str, via: str):
             logger.info(f"TwilioPhoneProvider._send_verification_code: verification status {verification.status}")
         except TwilioRestException as e:
             logger.error(f"Twilio verification start error: {e} to number {number}")
-            raise FailedToStartVerification
+            raise FailedToStartVerification(graceful_msg=self._get_graceful_msg(e, number))
 
     def _normalize_phone_number(self, number: str):
         # TODO: phone_provider: is it best place to parse phone number?