keep the login code when Kavenegar answers late instead of failing the request

Seen live on 2026-09-27: Kavenegar took 5.4 s, our 5 s timeout fired, the
API answered 503 and deleted the code, but the SMS arrived, so the site
said "service unavailable" while the phone held a code that no longer
worked. A read timeout now means "delivery unknown": the code is kept and
the request succeeds (the cooldown still blocks a second SMS). A failed
connection is still an explicit 503. Read timeout raised to 10 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

accounts/services.py

@@ -42,6 +42,14 @@ class SMSDeliveryError(APIException):
     default_code = 'sms_delivery_failed'
 
 
+class SMSDeliveryUncertain(SMSDeliveryError):
+    """
+    درخواست به کاوه‌نگار رسید ولی جوابش در مهلت نیامد؛ پیامک شاید رفته باشد.
+    ۲۰۲۶-۰۹-۲۷ دیده شد: پاسخ ۵٫۴ ثانیه طول کشید، ما با مهلتِ ۵ ثانیه ۵۰۳ دادیم و
+    کد را پاک کردیم، ولی پیامک رسید — کاربر کدی در دست داشت که دیگر کار نمی‌کرد.
+    """
+
+
 class OTPDeliveryError(SMSDeliveryError):
     """
     ⚠️ اصلاح: قبلاً send_otp_sms یک استاب بود که فقط لاگ می‌کرد و همیشه
@@ -95,6 +103,11 @@ def send_verify_lookup(*, phone: str, template: str, token: str) -> None:
     )
 
 
+# کاوه‌نگار گاهی بیش از ۵ ثانیه طول می‌کشد (۵٫۴ ثانیه در ۲۰۲۶-۰۹-۲۷)؛ workerهای
+# gunicorn مهلتِ ۱۲۰ ثانیه دارند و gthread است، پس ۱۰ ثانیه کسی را قفل نمی‌کند.
+SMS_READ_TIMEOUT_SECONDS = 10
+
+
 def _kavenegar_post(*, phone: str, method: str, payload: dict) -> None:
     """فراخوانیِ مشترکِ کاوه‌نگار و سنجشِ پاسخ؛ هر شکستی SMSDeliveryError است."""
     if not settings.KAVENEGAR_API_KEY:
@@ -108,8 +121,15 @@ def _kavenegar_post(*, phone: str, method: str, payload: dict) -> None:
         response = requests.post(
             f'https://api.kavenegar.com/v1/{settings.KAVENEGAR_API_KEY}/{method}',
             data=payload,
-            timeout=5,
+            # (اتصال، خواندن). وصل‌نشدن یعنی قطعاً نرفت؛ دیر رسیدنِ جواب یعنی نامعلوم.
+            timeout=(3.05, SMS_READ_TIMEOUT_SECONDS),
         )
+    except requests.ReadTimeout:
+        logger.warning(
+            'SMS provider reply timed out after the request was sent; delivery unknown: '
+            'phone_suffix=%s method=%s', _phone_suffix(phone), method,
+        )
+        raise SMSDeliveryUncertain('پاسخِ سرویسِ پیامک دیر رسید.')
     except requests.RequestException:
         logger.exception('SMS request to provider failed: phone_suffix=%s', _phone_suffix(phone))
         raise SMSDeliveryError('ارسال پیامک با خطا مواجه شد.')
@@ -181,6 +201,11 @@ def send_otp_sms(*, phone: str, code: str) -> None:
             send_verify_lookup(phone=phone, template=settings.KAVENEGAR_OTP_TEMPLATE, token=code)
         else:
             send_sms(phone=phone, message=settings.OTP_SMS_TEMPLATE.format(code=code))
+    except SMSDeliveryUncertain:
+        # کد نگه داشته می‌شود و پاسخ موفق است: اگر پیامک رسیده، همان کد کار می‌کند؛
+        # اگر نرسیده، کاربر بعد از cooldown کدِ تازه می‌خواهد. برعکسش (۵۰۳ و پاک کردنِ
+        # کد) کاربری را که پیامک گرفته قفل می‌کرد. cooldown جلوی دو پیامک را می‌گیرد.
+        return
     except SMSDeliveryError as exc:
         raise OTPDeliveryError(str(exc)) from exc