Если код приходит на российский номер, но не доходит на зарубежный, не отправляйте его десять раз подряд. Создайте одну тестовую попытку, сохраните внутренний `verification_id`, ответ SMS-провайдера и идентификатор попытки. Сначала подтвердите номер в международном формате E.164, затем проверьте разрешение страны и финальный статус доставки. Так видно, запрос не был принят вообще или был принят, но остановился дальше по маршруту.

Сообщение «код отправлен» в интерфейсе должно означать только то, что приложение зарегистрировало попытку. HTTP 200 или статус `pending` у Verify ещё не доказывает появление SMS на телефоне. Пользователю лучше показать нейтральное сообщение и доступный резервный канал, а подробную причину оставить в защищённом журнале без самого OTP.

Одна попытка становится трассировкой, а не догадкой

Для разбора нужны одинаковые поля на всех этапах: ваш request ID, хеш или маска номера, страна, канал, provider attempt ID, время в UTC, ответ API и последующие события. Полный номер и код подтверждения в обычный application log не попадают. Связь между событиями строится по внутреннему ID и идентификатору провайдера.

verification_id=ver_01J...
destination=+49******731
country=DE
channel=sms
provider_attempt=VLxxxxxxxxxxxxxxxx
accepted_at=2026-10-07T10:20:31Z
provider_status=pending
provider_error=null
НаблюдениеЧто уже известноСледующий шаг
API вернул 4xxсообщение не поставлено в маршрутпрочитать точный error code и request parameters
attempt создан, status pendingпровайдер принял задачуполучить status/error следующего события
blocked по географиистрана запрещена настройкой аккаунтасверить Geo Permissions и требования страны
undelivered/failed у операторазапрос дошёл дальше APIразобрать provider/carrier code и sender route
delivered, SMS нет в inboxоператор подтвердил доставку, но не чтениепроверить устройство, фильтр спама и правильность номера

Номер нормализуется до обращения к провайдеру

Twilio Verify требует телефон в формате E.164. Это плюс, код страны и национальная часть без пробелов и локального префикса набора. Нельзя просто удалить из ввода все нецифровые символы: ведущий ноль в национальном формате и код страны имеют разный смысл. Парсеру передают исходную строку и выбранную страну, а результат проверяют библиотекой телефонных номеров.

input:  030 1234567
region: DE
E.164:  +49301234567
stored: raw_input + region + e164
log:    +49******567
  • Не подставлять страну по IP как окончательное решение: VPN и поездка меняют геолокацию, но не номер.
  • Не хранить разные написания одного номера как разные аккаунты; ключом сравнения служит нормализованное значение.
  • Показывать пользователю распознанную страну и маскированный номер перед отправкой.
  • Отдельно обрабатывать номера, которые не соответствуют плану нумерации, до платного API-вызова.

Географическое разрешение не равно доступному маршруту

В Twilio Verify Geo Permissions управляют трафиком по странам. Отключённая страна блокирует отправку, а safe list может использоваться для ограниченного теста. У обычного Messaging ошибка 21408 указывает, что регион выключен или канал туда не поддерживается. Разрешать все страны ради одного инцидента опасно: форма OTP становится целью SMS pumping, и злоумышленник генерирует дорогой трафик.

После включения нужной страны всё равно проверяют требования назначения: тип sender, предварительную регистрацию бренда или шаблона, допустимый текст и поддержку конкретного канала. Настройка аккаунта не отменяет правила оператора и страны. Если маршрут не поддерживается, ошибка должна переводить пользователя на действительно доступный канал, а не запускать бесконечный retry.

Повторная отправка имеет состояние и лимит

Кнопка «Отправить ещё раз» не создаёт параллельные коды без контроля. Сервер хранит активную verification session, время последней попытки, число отправок и проверок, а также выбранный канал. Клиентский таймер нужен для интерфейса, но решение принимает сервер. Лимит задают как по аккаунту/номеру, так и по IP или устройству, чтобы не блокировать весь офис за действия одного пользователя.

  1. Если активная попытка ещё обрабатывается, вернуть её состояние без новой SMS.
  2. После разумной паузы разрешить resend в пределах серверного лимита.
  3. При явном permanent failure предложить другой разрешённый канал.
  4. После нескольких ошибок замедлить поток и потребовать дополнительный антифрод-сигнал.
  5. Не сообщать, зарегистрирован ли номер: одинаковый ответ снижает риск перебора аккаунтов.

Тестовая матрица отделяет страну от конкретного телефона

Возьмите по одному разрешённому тестовому номеру для каждой реально поддерживаемой страны и проверяйте их после изменения маршрута или sender. Для каждого запуска фиксируйте E.164, страну, тип номера, канал, provider attempt ID, принятие API, delivery status и фактическое получение. Один личный номер разработчика не представляет всех операторов страны.

СценарийОжидаемый результатЧто доказывает
разрешённая страна, корректный мобильный номерattempt принят и код полученбазовый маршрут работает
страна выключенапредсказуемый blocked/error без SMSgeo policy применяется
невалидная национальная строкаошибка до APIнормализация защищает бюджет
быстрые повторные нажатияодна активная сессия и rate limitнет SMS-лавины
SMS недоступна, fallback разрешёнпереход на voice/WhatsApp/email по политикерезервный путь реальный

Что приложить к заявке провайдеру

Если формат, страна и настройки верны, а попытки стабильно завершаются ошибкой у одного оператора, подготовьте время UTC, страну и маску номера, provider attempt ID, channel, sender, status и error code. Не прикладывайте OTP, auth token и полный номер в публичный тикет. После ответа повторите один контролируемый тест и сохраните результат рядом с изменением конфигурации.

Готовое исправление подтверждается не зелёным ответом API, а воспроизводимой доставкой на тестовых маршрутах, ограниченным resend и понятным fallback. Для повторного разбора достаточно обезличенного журнала одной попытки и списка стран, которые продукт действительно поддерживает.

Проверенные источники